@magicpixelart/cli 0.5.36 → 0.6.1

package/dist/commands/sync.js

@@ -1,5 +1,5 @@
 import kleur from 'kleur';
-import ora from 'ora';
+import { canRedraw, card, fitLine, formatDuration, icon, progressBar, spinner as makeSpinner, ui } from '../util/ui.js';
 import { mkdir, unlink, readdir, rm, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { dirname, relative, resolve } from 'node:path';
@@ -12,7 +12,7 @@ import { createLimit } from '../util/limit.js';
 import { emitTypedIndex, ensureAgentsDoc, scanDiskAssets } from '../util/emitIndex.js';
 import { assertPathInsideRoot, assertSafeIoPath } from '../util/security.js';
 import { detectProjectKind, isEngineKind } from '../util/framework.js';
-import { indexGamePngs, matchConnectGlobs, countingSpritesText } from '../util/gameScan.js';
+import { describeExcluded, indexGamePngs, matchConnectGlobs, countingSpritesText } from '../util/gameScan.js';
 import { aliasCollisionKeys, collectSourceRelMap, isPathInside, syncDiskPathFromKey } from '../util/syncPath.js';
 import { DEFAULT_UNITY_PPU, writeMissingUnityMetas } from '../util/unityMeta.js';
 import { filterUnityManifest, isWorkingSetEntry, partitionWithheldEntries, shouldPruneDeselectedEntry, workingSetPullKeys } from '../util/unityFilter.js';
@@ -23,7 +23,7 @@ import { maxIsoTimestamp } from '../util/iso.js';
 import { formatBytes } from '../util/format.js';
 import { computePreviousKeyOrphans } from '../util/previousKeyOrphans.js';
 import { cmd } from '../util/invoke.js';
-import { fitStatusLine, formatSlowTickLine, formatWatchSpriteLine, SLOW_TICK_HEARTBEAT_MS } from '../util/watchCopy.js';
+import { formatSlowTickLine, formatWatchSpriteLine, SLOW_TICK_HEARTBEAT_MS } from '../util/watchCopy.js';
 import { canSkipWithoutHashing, decidePull, hasNewExplicitRelease } from '../util/pullDecision.js';
 import { hasUnpushedLocalEdit } from '../util/localEdit.js';
 import { shouldReconcile } from '../util/reconcile.js';
@@ -31,6 +31,8 @@ import { runPush } from './push.js';
 import { claimResyncRequest, reportResyncRequest } from '../api.js';
 import { runResync } from './resync.js';
 import { keyInScope, pathInScope, resolveSyncScope, scopeFingerprint } from '../util/syncScope.js';
+import { findForeignOwner, foreignOwnerMessage, recordProjectRoot } from '../util/projectRoots.js';
+import { placeBesideSiblings, splitStrayDownloads, straySkipMessage } from '../util/strayGuard.js';
 /** How often the watcher asks for a library "Resync from game" request. */
 const RESYNC_POLL_MS = 15_000;
 let lastResyncPollAt = 0;
@@ -66,7 +68,7 @@ async function maybeRunQueuedResync(quiet) {
     catch (e) {
         await reportResyncRequest(req.id, 'failed', e.message).catch(() => { });
         if (!quiet)
-            console.log(kleur.red(`! Resync failed: ${e.message}`));
+            console.log(ui.fail(`Resync failed: ${e.message}`));
     }
 }
 /** Did the push half of a run actually move bytes into MagicPixel? */
@@ -87,7 +89,7 @@ export function pushWasActive(pushed) {
 export function needsLocalPngWalk(since, toDownloadCount) {
     return !since || toDownloadCount > 0;
 }
-export async function syncCommand(opts) {
+export async function syncCommand(opts, reuse = {}) {
     // Sweep any leaked `<file>.<pid>.<hex>.tmp` files left behind by a prior
     // crashed/killed CLI run before they pile up. Runs once per CLI invocation
     // (watch mode included) and only touches files older than 30s, so it can
@@ -109,7 +111,7 @@ export async function syncCommand(opts) {
         await watchLoop(opts);
         return;
     }
-    await runOnce(opts);
+    await runOnce(opts, { gameIndex: reuse.gameIndex });
 }
 async function watchLoop(opts) {
     // Default 2s — matches the perceived-instant UX users expect when editing
@@ -121,7 +123,7 @@ async function watchLoop(opts) {
     const intervalSec = typeof opts.watch === 'string' ? parseInt(opts.watch, 10) : 2;
     // Header — print once on start. Counts are best-effort; if the first
     // manifest fetch fails we still want the loop to come up and retry.
-    console.log(kleur.bold('👀 MagicPixel watching for changes…'));
+    console.log(card(`${icon('watch')} MagicPixel is watching for changes`, [`Edit at ${kleur.cyan('https://magicpixel.art')}`, kleur.dim('Changes show up here as they happen · Stop: Ctrl+C')], 'info'));
     console.log(`   Edit at:  ${kleur.cyan('https://magicpixel.art')}`);
     try {
         const scope = resolveSyncScope(opts.only ?? (await loadConfig()).syncOnly);
@@ -138,7 +140,7 @@ async function watchLoop(opts) {
             const config = await loadConfig();
             const kind = await detectProjectKind();
             if (isEngineKind(kind) && (config.connect?.length ?? 0) > 0) {
-                countSpinner = ora({ text: countingSpritesText(0), spinner: 'dots' }).start();
+                countSpinner = makeSpinner({ text: countingSpritesText(0), spinner: 'dots' }).start();
             }
         }
         catch {
@@ -155,6 +157,8 @@ async function watchLoop(opts) {
     else if (header.line && !opts.quiet) {
         console.log(kleur.dim(header.line));
     }
+    if (header.excluded && !opts.quiet)
+        console.log(kleur.yellow(`   ! ${header.excluded}`));
     console.log(kleur.dim(`   Polling:  every ${intervalSec}s (slows when idle)   ·   Stop: Ctrl+C`));
     console.log();
     let stopping = false;
@@ -188,7 +192,11 @@ async function watchLoop(opts) {
     let lastChangeAt = Date.now();
     // Re-walk the game tree on this cadence so new PNGs are ingested without
     // listing thousands of folders on every 2s tick.
-    const GAME_INDEX_TTL_MS = 30_000;
+    // Edits to already-indexed files are picked up every tick (push re-hashes
+    // them); the full tree walk only finds brand-new PNGs, so it runs rarely.
+    const GAME_INDEX_TTL_MS = 5 * 60_000;
+    const reportedIssues = new Set();
+    let reportedStrays = '';
     let gameIndexCache = header.gameIndex;
     let gameIndexAt = Date.now();
     // Cancellable idle sleep — `onStopSignal` calls `wakeStop()` so the next
@@ -225,9 +233,9 @@ async function watchLoop(opts) {
             return;
         inFlight = true;
         const onStatus = (msg) => {
-            if (opts.quiet)
-                return;
-            writeStatusLine(msg);
+            if (opts.quiet || !canRedraw())
+                return; // in-place updates only on a live terminal
+            process.stdout.write(`\r\x1b[2K${kleur.dim(fitStatusLine(`${timestamp()} ${msg}`, process.stdout.columns))}`);
         };
         // Heartbeat: a tick that legitimately takes minutes (huge first pull, slow
         // link) must not look like the silent hang a timeout-less fetch used to
@@ -247,7 +255,7 @@ async function watchLoop(opts) {
             }, SLOW_TICK_HEARTBEAT_MS);
         heartbeat?.unref?.();
         try {
-            wrappedStatus('Checking MagicPixel…');
+            wrappedStatus(`${icon('work')} Checking MagicPixel…`);
             const reuseIndex = gameIndexCache && Date.now() - gameIndexAt < GAME_INDEX_TTL_MS
                 ? gameIndexCache
                 : undefined;
@@ -275,15 +283,15 @@ async function watchLoop(opts) {
             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.`);
+                console.log(`${kleur.dim(timestamp())} ${icon('ok')} Key accepted again — resuming.`);
             }
             if (wasPausedForNetwork && !wasPausedForAuth && !opts.quiet) {
                 process.stdout.write('\x1b[2K\r');
-                console.log(`${kleur.dim(timestamp())} ${kleur.green('✓')} Back online — resuming.`);
+                console.log(`${kleur.dim(timestamp())} ${icon('ok')} 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.`);
+                console.log(`${kleur.dim(timestamp())} ${icon('ok')} 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
@@ -299,15 +307,37 @@ async function watchLoop(opts) {
             }
             if (opts.quiet)
                 return;
+            const sent = (r.pushed?.created ?? 0) + (r.pushed?.updated ?? 0);
+            const freshIssues = (r.pushed?.issues ?? []).filter((i) => !reportedIssues.has(`${i.key}\0${i.text}`));
+            const strayLine = r.strays ? `${r.strays.count}\0${r.strays.owner ?? ''}` : '';
+            if (sent > 0 || freshIssues.length > 0 || (strayLine && strayLine !== reportedStrays)) {
+                process.stdout.write('\x1b[2K\r');
+            }
+            if (sent > 0) {
+                console.log(`${kleur.dim(timestamp())} ${icon('up')} Sent ${ui.count(sent)} edited sprite${sent === 1 ? '' : 's'} to MagicPixel.`);
+            }
+            for (const i of freshIssues.slice(0, 10)) {
+                console.log(`${kleur.dim(timestamp())} ${icon('warn')} ${ui.name(i.key)}: ${i.text}`);
+            }
+            if (freshIssues.length > 10)
+                console.log(kleur.dim(`  …and ${freshIssues.length - 10} more not sent.`));
+            for (const i of freshIssues)
+                reportedIssues.add(`${i.key}\0${i.text}`);
+            if (strayLine && strayLine !== reportedStrays && r.strays) {
+                console.log(`${kleur.dim(timestamp())} ${icon('warn')} ${straySkipMessage(r.strays.count, r.strays.owner, `restart with ${kleur.cyan('--here')}`)}`);
+            }
+            reportedStrays = strayLine;
             if (changedCount > 0) {
                 process.stdout.write('\x1b[2K\r');
                 const verb = r.removed.length && !r.added.length && !r.modified.length ? 'Removed' : 'Pulled';
-                console.log(`${kleur.dim(timestamp())} ${kleur.green('✓')} ${verb} ${changedCount} ` +
+                console.log(`${kleur.dim(timestamp())} ${icon(verb === 'Removed' ? 'removed' : 'down')} ${verb} ${ui.count(changedCount)} ` +
                     `change${changedCount === 1 ? '' : 's'} from MagicPixel:`);
                 printChanges(r, /* indent */ '  ');
             }
             else {
-                writeStatusLine(`Waiting for edits… (${r.unchanged} up to date)`);
+                if (canRedraw()) {
+                    process.stdout.write(`\r\x1b[2K${kleur.dim(fitStatusLine(`${timestamp()} ${icon('watch')} Watching · all in sync (${r.unchanged.toLocaleString('en-US')} up to date)`, process.stdout.columns))}`);
+                }
             }
         }
         catch (e) {
@@ -330,15 +360,15 @@ async function watchLoop(opts) {
                     // Surface the request id (from B1) so the user can paste it into a
                     // support thread and we can correlate against edge function logs.
                     const idSuffix = apiErr?.requestId ? kleur.dim(` (request id: ${apiErr.requestId})`) : '';
-                    console.log(`${kleur.dim(timestamp())} ${kleur.red('✗')} Your key looks invalid or rotated.${idSuffix}`);
-                    console.log(kleur.dim(`   Fix: run \`${cmd('login')}\` (this watcher will keep retrying every 30s).`));
+                    console.log(`${kleur.dim(timestamp())} ${icon('fail')} Your key looks invalid or rotated.${idSuffix}`);
+                    console.log(`${ui.fix(cmd('login'))}${kleur.dim(` (this watcher will keep retrying every 30s).`)}`);
                 }
                 pausedForAuth = true;
                 consecutiveAuthFailures = decision.consecutiveAuthFailures;
                 backoffSec = decision.nextBackoffSec;
                 if (decision.giveUp) {
-                    console.log(`${kleur.dim(timestamp())} ${kleur.red('✗')} Giving up after ${MAX_AUTH_FAILURES} consecutive auth failures.`);
-                    console.log(kleur.dim(`   Fix: run \`${cmd('login')}\` with a fresh key, then restart the watcher.`));
+                    console.log(`${kleur.dim(timestamp())} ${icon('fail')} Giving up after ${MAX_AUTH_FAILURES} consecutive auth failures.`);
+                    console.log(`${ui.fix(cmd('login'))}${kleur.dim(` with a fresh key, then restart the watcher.`)}`);
                     // Surface this to /admin/errors — persistent watcher auth failure
                     // means a key is mass-rejected (revoked, project deleted, edge
                     // misconfig) and we want visibility without waiting for a support
@@ -351,7 +381,7 @@ async function watchLoop(opts) {
                 consecutiveAuthFailures = 0;
                 if (decision.printMessage) {
                     const idSuffix = apiErr?.requestId ? kleur.dim(` (request id: ${apiErr.requestId})`) : '';
-                    console.log(`${kleur.dim(timestamp())} ${kleur.yellow('!')} MagicPixel is offline or your internet is. ` +
+                    console.log(`${kleur.dim(timestamp())} ${icon('warn')} ${kleur.yellow('Paused')} — MagicPixel is offline or your internet is. ` +
                         `Sprites you already have still work. Retrying in ${decision.nextBackoffSec}s.${idSuffix}`);
                 }
                 pausedForNetwork = true;
@@ -361,7 +391,7 @@ async function watchLoop(opts) {
                 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. ` +
+                    console.log(`${kleur.dim(timestamp())} ${icon('warn')} 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}`);
                 }
@@ -371,7 +401,7 @@ async function watchLoop(opts) {
             else {
                 consecutiveAuthFailures = 0;
                 const idSuffix = apiErr?.requestId ? kleur.dim(` (request id: ${apiErr.requestId})`) : '';
-                console.log(`${kleur.dim(timestamp())} ${kleur.red('!')} ${firstLine}${idSuffix}`);
+                console.log(`${kleur.dim(timestamp())} ${icon('fail')} ${firstLine}${idSuffix}`);
                 backoffSec = decision.nextBackoffSec;
             }
         }
@@ -379,6 +409,10 @@ async function watchLoop(opts) {
             if (heartbeat)
                 clearInterval(heartbeat);
             inFlight = false;
+            if ((pausedForAuth || pausedForNetwork || pausedForQuota) && !opts.quiet && canRedraw()) {
+                const why = pausedForAuth ? 'waiting for a valid key' : pausedForQuota ? 'daily allowance reached' : 'offline';
+                process.stdout.write(`\r\x1b[2K${kleur.yellow(fitStatusLine(`${timestamp()} ${icon('paused')} Paused (${why}) · retrying in ${formatDuration(backoffSec * 1000)}`, process.stdout.columns))}`);
+            }
         }
     };
     await tick();
@@ -507,15 +541,18 @@ async function loadWatchHeader(onProgress) {
         const lastPulled = state.assets ? Object.keys(state.assets).length : 0;
         let workingSet = 0;
         let gameIndex;
+        let excluded = null;
         const kind = await detectProjectKind();
         if (isEngineKind(kind) && (config.connect?.length ?? 0) > 0) {
             gameIndex = await indexGamePngs(kind, process.cwd(), config.outDir, { onProgress });
-            workingSet = matchConnectGlobs(gameIndex, config.connect, config.exclude).entries.length;
+            const matched = matchConnectGlobs(gameIndex, config.connect, config.exclude);
+            workingSet = matched.entries.length;
+            excluded = describeExcluded(matched);
         }
         else if (state.synced) {
             workingSet = Object.keys(state.synced).length;
         }
-        return { line: formatWatchSpriteLine({ workingSet, lastPulled }), gameIndex };
+        return { line: formatWatchSpriteLine({ workingSet, lastPulled }), excluded, gameIndex };
     }
     catch {
         return { line: null };
@@ -536,7 +573,7 @@ async function runOnce(opts, runOpts = {}) {
     const onStatus = runOpts.onStatus;
     const shouldPrune = opts.prune !== false; // commander: --no-prune sets false
     if (verbose && config.endpoint) {
-        console.log(kleur.yellow(`! using custom endpoint: ${config.endpoint}`));
+        console.log(ui.warn(`using custom endpoint: ${config.endpoint}`));
     }
     // Incremental unless asked for a full run — or unless a full pass is due:
     // permanently-deleted rows can't be reported incrementally (see reconcile.ts).
@@ -553,7 +590,7 @@ async function runOnce(opts, runOpts = {}) {
         since = undefined;
     const previousAssets = state.assets ?? {}; // id → key from prior sync
     const spinner = verbose
-        ? ora(since ? `Fetching manifest since ${humanTime(since)}…` : 'Fetching manifest…').start()
+        ? makeSpinner(since ? `Fetching manifest since ${humanTime(since)}…` : 'Fetching manifest…').start()
         : null;
     if (!spinner)
         onStatus?.(since ? 'Checking MagicPixel for edits…' : 'Fetching your sprites from MagicPixel…');
@@ -602,7 +639,7 @@ async function runOnce(opts, runOpts = {}) {
         if (resetStateIfProjectChanged(state, projectInfo?.id, !since && snapshot.entries.length === 0)) {
             await saveState(state);
             if (verbose)
-                console.log(kleur.yellow(`! ${PROJECT_CHANGED_MESSAGE}`));
+                console.log(ui.warn(`${PROJECT_CHANGED_MESSAGE}`));
         }
         const projectSuffix = projectInfo && verbose
             ? kleur.dim(` · project: ${projectInfo.name ?? projectInfo.id.slice(0, 8)}`)
@@ -614,7 +651,7 @@ async function runOnce(opts, runOpts = {}) {
         // so the user isn't left wondering why sync "did nothing".
         if (!since && manifest.length === 0 && projectInfo?.hint && verbose) {
             console.log();
-            console.log(kleur.yellow(`! ${projectInfo.hint}`));
+            console.log(ui.warn(`${projectInfo.hint}`));
         }
     }
     catch (e) {
@@ -626,7 +663,7 @@ async function runOnce(opts, runOpts = {}) {
             const pushed = await maybePushLocalSprites(config.push, verbose);
             if (verbose && pushed && pushed.created > 0) {
                 console.log();
-                console.log(kleur.green(`✓ pushed ${pushed.created} working-set sprite${pushed.created === 1 ? '' : 's'} into MagicPixel anyway.`));
+                console.log(ui.ok(`pushed ${pushed.created} working-set sprite${pushed.created === 1 ? '' : 's'} into MagicPixel anyway.`));
                 console.log(kleur.dim('  Refresh Connected in the library to see them, then re-run sync to pull.'));
             }
         }
@@ -642,11 +679,9 @@ async function runOnce(opts, runOpts = {}) {
                 onProgress: (p) => {
                     const n = p.pngs.toLocaleString('en-US');
                     const f = p.folders.toLocaleString('en-US');
-                    onStatus?.(p.current
-                        ? `Looking through your game sprites…  ${n} sprites · ${f} folders  ·  ${p.current}`
-                        : p.folders > 0
-                            ? `Looking through your game sprites…  ${n} sprites · ${f} folders`
-                            : `Looking through your game sprites…  ${n}`);
+                    onStatus?.(p.folders > 0
+                        ? `Looking through your game sprites…  ${n} sprites · ${f} folders`
+                        : `Looking through your game sprites…  ${n}`);
                 },
             })
             : { files: [] });
@@ -686,8 +721,20 @@ async function runOnce(opts, runOpts = {}) {
         }
     }
     aliasCollisionKeys(sourceByKey, manifest.map((e) => e.key));
+    if (isEngineKind(projectKind)) {
+        placeBesideSiblings(sourceByKey, manifest, new Set(fullGameIndex.files.map((f) => f.sourceRel)));
+    }
+    if (verbose && gameIndex.keyClashes?.length) {
+        console.log(ui.warn(`${gameIndex.keyClashes.length} file${gameIndex.keyClashes.length === 1 ? '' : 's'} share a name with a file in another game folder — skipped:`));
+        for (const r of gameIndex.keyClashes.slice(0, 5))
+            console.log(kleur.dim(`    ${r}`));
+        console.log(ui.fixText('rename one of them so each sprite has its own name.'));
+    }
     if (verbose && isEngineKind(projectKind)) {
         console.log(kleur.dim(`  game index → ${gameIndex.files.length} PNG${gameIndex.files.length === 1 ? '' : 's'} · working set ${connected.entries.length}`));
+        const skipped = describeExcluded(connected);
+        if (skipped)
+            console.log(kleur.dim(`  ${skipped}`));
     }
     const pathForKey = (key) => syncDiskPathFromKey(config.outDir, key, sourceByKey);
     // Every folder on disk that belongs to a withheld document. Anything already
@@ -719,8 +766,8 @@ async function runOnce(opts, runOpts = {}) {
             const n = filtered.unknown.length;
             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\`.`));
+                console.log(ui.warn(`${msg}`));
+                console.log(ui.fixText(`re-run \`${cmd('sync')}\` in a moment, or upgrade with \`npm i -D @magicpixelart/cli@latest\`.`));
             }
             else {
                 onStatus?.(msg);
@@ -788,7 +835,7 @@ async function runOnce(opts, runOpts = {}) {
         : 'Checking MagicPixel…');
     const diffLimit = createLimit(concurrency);
     const shaByEntryId = new Map();
-    const toDownload = [];
+    let toDownload = [];
     const conflicts = [];
     const failedDownloadKeys = new Set();
     let bytesSaved = 0;
@@ -879,6 +926,37 @@ async function runOnce(opts, runOpts = {}) {
     const remoteDiskPaths = new Set(manifest.map((e) => pathFor(e)));
     const remoteKeySet = new Set(manifest.map((e) => e.key));
     const previousKeySet = new Set(Object.values(previousAssets));
+    // Wrong-folder guard: sprites connected to another game folder on this
+    // machine would land here as stray copies under outDir. Stop before writing.
+    const projectIdForRoots = getLastProjectInfo()?.id;
+    // Game-owned sprites (server flag) with no home in this folder are skipped —
+    // this works even on a machine where the owning folder never synced.
+    let strays;
+    if (!opts.here) {
+        const split = splitStrayDownloads(toDownload, [...sourceByKey.keys(), ...connected.entries.map((e) => e.key)]);
+        if (split.foreign.length > 0) {
+            toDownload = split.keep;
+            const owner = projectIdForRoots
+                ? await findForeignOwner(projectIdForRoots, process.cwd(), split.foreign.map((e) => e.key))
+                : null;
+            strays = { count: split.foreign.length, owner: owner?.root ?? null };
+            if (verbose) {
+                console.log();
+                console.log(ui.warn(straySkipMessage(strays.count, strays.owner, `add ${kleur.cyan('--here')}`)));
+            }
+        }
+    }
+    if (projectIdForRoots && !opts.here) {
+        const owner = await findForeignOwner(projectIdForRoots, process.cwd(), toDownload.filter((e) => !sourceByKey.has(e.key)).map((e) => e.key));
+        if (owner) {
+            const msg = foreignOwnerMessage(owner, process.cwd(), `add ${kleur.cyan('--here')}`);
+            if (runOpts.watchMode) {
+                console.error(kleur.red(msg));
+                process.exit(1);
+            }
+            throw new Error(msg);
+        }
+    }
     const localPngs = needsLocalPngWalk(since, toDownload.length)
         ? await walkOutDirPngs(config.outDir)
         : [];
@@ -1119,7 +1197,7 @@ async function runOnce(opts, runOpts = {}) {
     }
     if (opts.dryRun) {
         if (verbose) {
-            console.log(kleur.dim('--dry-run: no files written.'));
+            console.log(ui.dryRun());
             if (renamed.length > 0)
                 printRenames(renamed, { withHints: false });
             if (orphans.length > 0)
@@ -1153,7 +1231,7 @@ async function runOnce(opts, runOpts = {}) {
     let progress = null;
     if (live && toDownload.length > 0) {
         onStatus?.(`Pulling ${toDownload.length.toLocaleString('en-US')} updated sprite${toDownload.length === 1 ? '' : 's'}…`);
-        progress = ora({ text: progressText(0, toDownload.length, 0), spinner: 'dots' }).start();
+        progress = makeSpinner({ text: progressText(0, toDownload.length, 0), spinner: 'dots' }).start();
     }
     const run = createLimit(concurrency);
     let done = 0;
@@ -1223,12 +1301,12 @@ async function runOnce(opts, runOpts = {}) {
             // so the user sees the fix hint. Single-line errors stay terse.
             const msg = e.message ?? String(e);
             if (msg.includes('\n')) {
-                console.log(`  ${kleur.red('!')} ${entry.key}:`);
+                console.log(`  ${icon('fail')} ${entry.key}:`);
                 for (const line of msg.split('\n'))
                     console.log(`     ${line}`);
             }
             else {
-                console.log(`  ${kleur.red('!')} ${entry.key}: ${msg}`);
+                console.log(`  ${icon('fail')} ${entry.key}: ${msg}`);
             }
             progress?.start();
         }
@@ -1285,7 +1363,7 @@ async function runOnce(opts, runOpts = {}) {
             }
             catch (e) {
                 if (verbose)
-                    console.log(`  ${kleur.yellow('!')} failed to prune ${relative(process.cwd(), p)}: ${e.message}`);
+                    console.log(`  ${icon('warn')} failed to prune ${relative(process.cwd(), p)}: ${e.message}`);
             }
         }
         await pruneEmptyDirs(resolve(process.cwd(), config.outDir));
@@ -1313,7 +1391,7 @@ async function runOnce(opts, runOpts = {}) {
             }
             catch (e) {
                 if (verbose)
-                    console.log(`  ${kleur.yellow('!')} failed to remove legacy folder ${relative(process.cwd(), lf.abs)}: ${e.message}`);
+                    console.log(`  ${icon('warn')} failed to remove legacy folder ${relative(process.cwd(), lf.abs)}: ${e.message}`);
             }
         }
         // Always surface the import-update notice — even in --quiet/watch mode
@@ -1485,6 +1563,11 @@ async function runOnce(opts, runOpts = {}) {
         // Never let an AGENTS.md write failure break sync.
     }
     await saveState(nextState);
+    // This folder owns real game paths → remember it so a sync elsewhere can
+    // point back here instead of writing stray copies.
+    if (projectIdForRoots && sourceByKey.size > 0) {
+        await recordProjectRoot(projectIdForRoots, process.cwd());
+    }
     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.`));
     }
@@ -1492,23 +1575,28 @@ async function runOnce(opts, runOpts = {}) {
     const pushed = await maybePushLocalSprites(config.push, verbose, scopedGameIndex, live && !!runOpts.watchMode, onStatus, conflictSet);
     if (verbose) {
         console.log();
-        const summary = `downloaded ${downloaded} (added ${result.added.length}, modified ${result.modified.length}), ` +
-            `unchanged ${result.unchanged}` +
-            (result.bytesSaved ? kleur.dim(` (~${formatBytes(result.bytesSaved)} saved)`) : '') +
-            (shouldPrune ? `, pruned ${result.removed.length}` : '') +
-            (renamed.length ? `, renamed ${renamed.length}` : '') +
-            (result.failed ? `, failed ${result.failed}` : '');
         const pushFailed = (pushed?.conflict ?? 0) + (pushed?.error ?? 0);
+        const skipped = pushed?.issues.length ?? 0;
+        const sent = (pushed?.created ?? 0) + (pushed?.updated ?? 0);
+        const rows = [
+            `${icon('down')} ${ui.count(downloaded)} downloaded   ${icon('up')} ${ui.count(sent)} uploaded`,
+            `${icon('ok')} ${ui.count(result.unchanged)} unchanged` +
+                (shouldPrune && result.removed.length ? `   ${icon('removed')} ${ui.count(result.removed.length)} removed` : '') +
+                (skipped ? `   ${icon('warn')} ${ui.count(skipped)} skipped` : ''),
+            ...(renamed.length ? [`↪ ${ui.count(renamed.length)} renamed — see below`] : []),
+            ...(result.failed || pushFailed ? [`${icon('fail')} ${ui.count(result.failed + pushFailed)} failed — re-run to retry`] : []),
+            kleur.dim(`${icon('time')} ${formatDuration(Date.now() - Date.parse(startedAt))}${result.bytesSaved ? ` · ~${formatBytes(result.bytesSaved)} saved` : ''}`),
+        ];
         console.log(result.failed || pushFailed
-            ? kleur.yellow(`Sync finished with issues. ${summary}`)
-            : kleur.green(`✓ Sync complete. ${summary}`));
+            ? card(`${icon('warn')} Sync finished with issues`, rows, 'warn')
+            : card(`${icon('sparkle')} Sync complete`, rows, 'ok'));
         printChanges(result, '  ', { includeRenames: renamed.length === 0 });
         if (renamed.length > 0)
             printRenames(renamed, { withHints: true });
     }
     if (result.failed)
         process.exitCode = 1;
-    return { ...result, pushed };
+    return { ...result, pushed, ...(strays ? { strays } : {}) };
 }
 async function maybePushLocalSprites(pushEnabled, verbose, gameIndex, announceErrors = verbose, onStatus, excludeKeys) {
     if (pushEnabled === false)
@@ -1519,8 +1607,8 @@ async function maybePushLocalSprites(pushEnabled, verbose, gameIndex, announceEr
     catch (e) {
         if (announceErrors) {
             console.log();
-            console.log(kleur.yellow(`! could not update MagicPixel from your game files: ${e.message}`));
-            console.log(kleur.dim(`  Fix: run \`${cmd('push')}\` once the connection is healthy.`));
+            console.log(ui.warn(`could not update MagicPixel from your game files: ${e.message}`));
+            console.log(ui.fixText(`run \`${cmd('push')}\` once the connection is healthy.`));
         }
         return null;
     }
@@ -1564,16 +1652,11 @@ function printRenames(renamed, opts) {
     }
 }
 function progressText(done, total, bytes) {
-    const pct = total === 0 ? 100 : Math.round((done / total) * 100);
-    const barWidth = 24;
-    const filled = Math.round((pct / 100) * barWidth);
-    const bar = '█'.repeat(filled) + '░'.repeat(barWidth - filled);
-    return `${bar}  ${done}/${total}  ${kleur.dim(formatBytes(bytes))}`;
+    return `${icon('down')} ${progressBar(done, total)}  ${kleur.dim(formatBytes(bytes))}`;
 }
-/** Rewrite the watcher's single status row, clipped so it never wraps. */
-function writeStatusLine(msg) {
-    const line = fitStatusLine(`${timestamp()} ${msg}`, process.stdout.columns);
-    process.stdout.write(`\r\x1b[2K${kleur.dim(line)}`);
+/** Cut a status line to the terminal width so `\r` redraws never wrap. */
+export function fitStatusLine(line, columns) {
+    return fitLine(line, columns);
 }
 function timestamp() {
     const d = new Date();

package/dist/commands/whoami.js

@@ -1,4 +1,5 @@
 import kleur from 'kleur';
+import { ui } from '../util/ui.js';
 import { loadConfig, defaultConfig, resolveEndpoint, getApiKey } from '../config.js';
 import { ApiError, errorCodeFromResponse, friendlyApiError, retryTransient, retryAfterMsFromResponse, getLastProjectInfo } from '../api.js';
 import { safeFetch } from '../util/security.js';
@@ -71,21 +72,21 @@ export async function whoamiCommand() {
         return { kind: 'ok', body, project, serverRequestId };
     });
     if (result.kind === 'rejected') {
-        console.log(kleur.red(`✗ API key rejected (${result.status}).`));
+        console.log(ui.fail(`API key rejected (${result.status}).`));
         console.log(kleur.dim('  Generate a new key at MagicPixel → Settings → API Keys.'));
         console.log(kleur.dim(`  (request id: ${result.serverRequestId})`));
         process.exitCode = 1;
         return;
     }
     if (result.kind === 'error') {
-        console.log(kleur.red(`✗ ${result.status}: ${result.bodyText.slice(0, 200)}`));
+        console.log(ui.fail(`${result.status}: ${result.bodyText.slice(0, 200)}`));
         console.log(kleur.dim(`  (request id: ${result.serverRequestId})`));
         process.exitCode = 1;
         return;
     }
     const { body, project } = result;
     const more = body.nextCursor ? '+' : '';
-    console.log(kleur.green('✓ key valid'));
+    console.log(ui.ok('key valid'));
     console.log(`  endpoint: ${resolveEndpoint(config)}`);
     if (project) {
         const label = project.name ?? '(unnamed)';

package/dist/commands/why.js

@@ -0,0 +1,91 @@
+import kleur from 'kleur';
+import { spinner as makeSpinner } from '../util/ui.js';
+import { loadConfig, loadState } from '../config.js';
+import { detectProjectKind, isEngineKind } from '../util/framework.js';
+import { countingSpritesText, entryMatchesGlob, indexGamePngs, rootSpriteDotDirs } from '../util/gameScan.js';
+import { hashFile } from '../util/hash.js';
+import { indexSyncedBySourceRel, resolveSyncedKey } from '../util/pushPlan.js';
+import { normalizeScopeFolder } from '../util/syncScope.js';
+import { cmd } from '../util/invoke.js';
+import { resolveInvokedPath } from '../util/workspace.js';
+import { relative } from 'node:path';
+/** What the next sync does with one game PNG — no network, local facts only. */
+export function explainSprite(entry, config, synced, currentSha) {
+    const hit = (g) => entryMatchesGlob(entry, g);
+    if (!(config.connect ?? []).some(hit))
+        return { kind: 'not-watched' };
+    const rule = (config.exclude ?? []).find(hit);
+    if (rule !== undefined)
+        return { kind: 'excluded', rule };
+    const stateKey = resolveSyncedKey({ key: entry.key, sourceRel: entry.sourceRel }, synced, indexSyncedBySourceRel(synced));
+    const known = stateKey ? synced[stateKey] : undefined;
+    if (!known)
+        return { kind: 'new' };
+    if (known.legacy)
+        return { kind: 'legacy' };
+    if (currentSha && known.diskSha256 === currentSha)
+        return { kind: 'unchanged' };
+    return { kind: 'changed', ...(typeof known.layers === 'number' ? { layers: known.layers } : {}) };
+}
+export function describeVerdict(v, config) {
+    switch (v.kind) {
+        case 'not-watched':
+            return `not watched — no "connect" pattern matches it (${(config.connect ?? []).join(', ') || 'none'}). Fix: ${cmd('connect')} '<folder>/**'`;
+        case 'excluded':
+            return `skipped by exclude rule "${v.rule}" — remove it from "exclude" in magicpixel.json to sync this file`;
+        case 'new':
+            return 'new — the next sync adds it to MagicPixel';
+        case 'changed':
+            return v.layers && v.layers > 1
+                ? `changed locally, but the MagicPixel artboard has ${v.layers} layers — run \`${cmd('push')} --flatten\` to replace it`
+                : 'changed locally — the next sync uploads it';
+        case 'unchanged':
+            return 'unchanged since the last sync';
+        case 'legacy':
+            return 'linked to a legacy single-image file — open it in MagicPixel and save once, then sync again';
+    }
+}
+export async function whyCommand(pathArg) {
+    const config = await loadConfig();
+    const state = await loadState();
+    const kind = await detectProjectKind();
+    if (!isEngineKind(kind)) {
+        console.log(kleur.yellow('This folder is not a Unity/Godot/GameMaker project — sync only downloads here, it never uploads.'));
+        return;
+    }
+    const target = normalizeScopeFolder(resolveInvokedPath(pathArg)).toLowerCase();
+    const spinner = makeSpinner({ text: countingSpritesText(0), spinner: 'dots' }).start();
+    const index = await indexGamePngs(kind, process.cwd(), config.outDir, {
+        onProgress: (p) => { spinner.text = countingSpritesText(p); },
+    });
+    spinner.stop();
+    const files = index.files.filter((e) => {
+        const rel = e.sourceRel.toLowerCase();
+        return rel === target || rel.startsWith(`${target}/`);
+    });
+    if (files.length === 0) {
+        const dots = (await rootSpriteDotDirs(process.cwd())).map((d) => relative(process.cwd(), d));
+        console.log(kleur.yellow(`No PNGs found under ${pathArg} (scanned ${index.files.length.toLocaleString('en-US')} PNGs).`));
+        const scanned = config.members?.length ? config.members.map((m) => `${m}/`).join(', ') : `Assets/${dots.length ? `, ${dots.join(', ')}` : ''}`;
+        console.log(kleur.dim(`  Paths are relative to ${process.cwd()}. Scanned: ${scanned}.`));
+        return;
+    }
+    const synced = state.synced ?? {};
+    const counts = new Map();
+    const lines = [];
+    for (const e of files) {
+        const sha = (await hashFile(e.abs))?.sha256 ?? null;
+        const text = describeVerdict(explainSprite(e, config, synced, sha), config);
+        counts.set(text, (counts.get(text) ?? 0) + 1);
+        if (lines.length < 20)
+            lines.push(`  ${e.sourceRel}\n    ${kleur.dim('→')} ${text}`);
+    }
+    console.log(kleur.bold(`${files.length.toLocaleString('en-US')} PNG${files.length === 1 ? '' : 's'} under ${pathArg}:`));
+    for (const [text, n] of [...counts.entries()].sort((a, b) => b[1] - a[1])) {
+        console.log(`  ${kleur.cyan(String(n).padStart(5))}  ${text}`);
+    }
+    console.log();
+    console.log(lines.join('\n'));
+    if (files.length > lines.length)
+        console.log(kleur.dim(`  …and ${files.length - lines.length} more`));
+}