@magicpixelart/cli 0.5.9 → 0.5.11

package/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.5.11] — 2026-08-26
+
+### Changed
+
+- **Sprite counting shows a running total** (`Counting sprites in your
+  game…  1,247`) while walking the project, and watch reuses that first
+  scan so startup does not walk the tree twice.
+
+## [0.5.10] — 2026-08-26
+
+### Changed
+
+- **Watch header shows the working-set size**, not only the last successful
+  pull. Connecting 2,000+ game sprites no longer prints `Sprites: 469` when
+  `state.json` hasn't caught up yet (`2,147 in your game · 469 last pulled
+  from MagicPixel`).
+- **Watch prints live status** while a tick is in flight (`Checking
+  MagicPixel…`, `Comparing N sprites…`, download progress, `Checking your
+  game files…`) instead of sitting silent on the header until the tick
+  finishes. Idle ticks say `Waiting for edits…`.
+
 ## [0.5.9] — 2026-08-26
 
 ### Security

package/dist/commands/connect.js

@@ -1,8 +1,9 @@
 import kleur from 'kleur';
+import ora from 'ora';
 import { loadConfig, saveConfig } from '../config.js';
 import { assertSafeGlob } from '../util/security.js';
 import { detectProjectKind, isEngineKind } from '../util/framework.js';
-import { indexGamePngs, matchConnectGlobs, GAME_INDEX_CAP_HINT, connectCapMessage } from '../util/gameScan.js';
+import { indexGamePngs, matchConnectGlobs, GAME_INDEX_CAP_HINT, connectCapMessage, countingSpritesText } from '../util/gameScan.js';
 import { cmd } from '../util/invoke.js';
 import { runPush } from './push.js';
 /**
@@ -26,7 +27,11 @@ export async function connectCommand(glob) {
         console.log(kleur.yellow('  This folder is not a Unity/Godot/GameMaker project — nothing to ingest from disk.'));
         return;
     }
-    const index = await indexGamePngs(kind, process.cwd(), config.outDir);
+    const spinner = ora({ text: countingSpritesText(0), spinner: 'dots' }).start();
+    const index = await indexGamePngs(kind, process.cwd(), config.outDir, {
+        onProgress: (n) => { spinner.text = countingSpritesText(n); },
+    });
+    spinner.stop();
     if (index.capped) {
         console.log(kleur.yellow(`! ${GAME_INDEX_CAP_HINT}`));
     }

package/dist/commands/push.js

@@ -19,7 +19,7 @@ import { assetDiskPathFromKey, walkOutDirPngs } from '../util/paths.js';
 import { applyDiskFingerprints, indexSyncedBySourceRel, planPush, resolveSyncedKey } from '../util/pushPlan.js';
 import { cmd } from '../util/invoke.js';
 import { detectProjectKind, isEngineKind } from '../util/framework.js';
-import { indexGamePngs, matchConnectGlobs, GAME_INDEX_CAP_HINT, connectCapMessage } from '../util/gameScan.js';
+import { indexGamePngs, matchConnectGlobs, GAME_INDEX_CAP_HINT, connectCapMessage, countingSpritesText } from '../util/gameScan.js';
 import { collectSourceRelMap, remapAbsToCloudKeys } from '../util/syncPath.js';
 import { assertSafeIoPath } from '../util/security.js';
 /** Parallel hashing / path checks — enough to saturate disk, low enough to stay polite. */
@@ -42,11 +42,13 @@ 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 };
-    const spinner = quiet ? null : ora('Scanning local sprites…').start();
+    const spinner = quiet ? null : ora(countingSpritesText(0)).start();
     const kind = await detectProjectKind();
     const index = opts.gameIndex
         ?? (isEngineKind(kind)
-            ? await indexGamePngs(kind, process.cwd(), config.outDir)
+            ? await indexGamePngs(kind, process.cwd(), config.outDir, {
+                onProgress: spinner ? (n) => { spinner.text = countingSpritesText(n); } : undefined,
+            })
             : { files: [], capped: false });
     const matched = matchConnectGlobs(index, config.connect ?? []);
     const sourceByKey = collectSourceRelMap(matched.entries, state.synced);

package/dist/commands/search.js

@@ -1,7 +1,8 @@
 import kleur from 'kleur';
+import ora from 'ora';
 import { loadConfig } from '../config.js';
 import { detectProjectKind, isEngineKind } from '../util/framework.js';
-import { indexGamePngs, searchGameIndex, GAME_INDEX_CAP_HINT } from '../util/gameScan.js';
+import { indexGamePngs, searchGameIndex, GAME_INDEX_CAP_HINT, countingSpritesText } from '../util/gameScan.js';
 import { cmd } from '../util/invoke.js';
 const PRINT_CAP = 50;
 /**
@@ -25,7 +26,11 @@ export async function searchCommand(query) {
     catch {
         // Config is optional for search — skip MagicPixel outDir when missing.
     }
-    const index = await indexGamePngs(kind, process.cwd(), outDir);
+    const spinner = ora({ text: countingSpritesText(0), spinner: 'dots' }).start();
+    const index = await indexGamePngs(kind, process.cwd(), outDir, {
+        onProgress: (n) => { spinner.text = countingSpritesText(n); },
+    });
+    spinner.stop();
     if (index.capped) {
         console.log(kleur.yellow(`! ${GAME_INDEX_CAP_HINT}`));
     }

package/dist/commands/sync.js

@@ -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, GAME_INDEX_CAP_HINT, connectCapMessage } from '../util/gameScan.js';
+import { indexGamePngs, matchConnectGlobs, GAME_INDEX_CAP_HINT, connectCapMessage, countingSpritesText } from '../util/gameScan.js';
 import { collectSourceRelMap, isPathInside, syncDiskPathFromKey } from '../util/syncPath.js';
 import { DEFAULT_UNITY_PPU, writeMissingUnityMetas } from '../util/unityMeta.js';
 import { filterUnityManifest } from '../util/unityFilter.js';
@@ -23,6 +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 { formatWatchSpriteLine } from '../util/watchCopy.js';
 import { runPush } from './push.js';
 export async function syncCommand(opts) {
     // Sweep any leaked `<file>.<pid>.<hex>.tmp` files left behind by a prior
@@ -50,20 +51,33 @@ async function watchLoop(opts) {
     // Commander already validated the numeric value (2–3600); the `?? 2`
     // covers the bare boolean `-w` form.
     const intervalSec = typeof opts.watch === 'string' ? parseInt(opts.watch, 10) : 2;
-    // Header — print once on start. Project/asset count is best-effort; if the
-    // first manifest fetch fails we still want the loop to come up and retry.
-    let headerCount = null;
-    try {
-        const state = await loadState();
-        headerCount = state.assets ? Object.keys(state.assets).length : null;
-    }
-    catch {
-        // ignore — header is cosmetic
-    }
+    // 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(`   Edit at:  ${kleur.cyan('https://magicpixel.art')}`);
-    if (headerCount !== null)
-        console.log(kleur.dim(`   Sprites:  ${headerCount}`));
+    let countSpinner = null;
+    if (!opts.quiet) {
+        try {
+            const config = await loadConfig();
+            const kind = await detectProjectKind();
+            if (isEngineKind(kind) && (config.connect?.length ?? 0) > 0) {
+                countSpinner = ora({ text: countingSpritesText(0), spinner: 'dots' }).start();
+            }
+        }
+        catch {
+            /* header is cosmetic */
+        }
+    }
+    const header = await loadWatchHeader(countSpinner ? (n) => { countSpinner.text = countingSpritesText(n); } : undefined);
+    if (countSpinner) {
+        if (header.line)
+            countSpinner.succeed(header.line.trim());
+        else
+            countSpinner.stop();
+    }
+    else if (header.line && !opts.quiet) {
+        console.log(kleur.dim(header.line));
+    }
     console.log(kleur.dim(`   Polling:  every ${intervalSec}s (slows when idle)   ·   Stop: Ctrl+C`));
     console.log();
     let stopping = false;
@@ -106,12 +120,12 @@ async function watchLoop(opts) {
         wakeStop();
         process.stdout.write('\x1b[2K\r');
         if (inFlight) {
-            console.log(kleur.dim(`[watch] finishing current sync… (${signal} again to force quit)`));
+            console.log(kleur.dim(`Still finishing this check… (${signal} again to stop now)`));
             process.once(signal, () => process.exit(signal === 'SIGINT' ? 130 : 143));
         }
         else {
             if (!opts.quiet)
-                console.log(kleur.dim('[watch] stopped.'));
+                console.log(kleur.dim('Stopped watching.'));
             // Preserve any exit code already set by a prior failed tick.
             process.exit(process.exitCode ?? 0);
         }
@@ -122,8 +136,14 @@ async function watchLoop(opts) {
         if (inFlight || stopping)
             return;
         inFlight = true;
+        const onStatus = (msg) => {
+            if (opts.quiet)
+                return;
+            process.stdout.write(`\r\x1b[2K${kleur.dim(`${timestamp()} ${msg}`)}`);
+        };
         try {
-            const r = await runOnce({ ...opts, watch: false }, { watchMode: true });
+            onStatus('Checking MagicPixel…');
+            const r = await runOnce({ ...opts, watch: false }, { watchMode: true, onStatus, gameIndex: header.gameIndex });
             // Reset backoff on any successful tick. Resume message fires once when
             // we recover from an auth pause — `getApiKey()` re-reads
             // .magicpixel/credentials on every call, so a `magicpixel login` in
@@ -165,7 +185,7 @@ async function watchLoop(opts) {
                 printChanges(r, /* indent */ '  ');
             }
             else {
-                process.stdout.write(`\r\x1b[2K${kleur.dim(`${timestamp()} no changes (${r.unchanged} unchanged)`)}`);
+                process.stdout.write(`\r\x1b[2K${kleur.dim(`${timestamp()} Waiting for edits… (${r.unchanged} up to date)`)}`);
             }
         }
         catch (e) {
@@ -222,6 +242,7 @@ async function watchLoop(opts) {
             }
         }
         finally {
+            header.gameIndex = undefined;
             inFlight = false;
         }
     };
@@ -248,7 +269,7 @@ async function watchLoop(opts) {
         await tick();
     }
     if (!opts.quiet)
-        console.log(kleur.dim('[watch] stopped.'));
+        console.log(kleur.dim('Stopped watching.'));
     // Preserve any non-zero exit code set by a failed tick — don't mask a
     // download failure with a clean exit just because the user pressed Ctrl+C.
     process.exit(process.exitCode ?? 0);
@@ -309,12 +330,35 @@ export function classifyTickError(err, state) {
     }
     return { kind: 'other', nextBackoffSec: Math.min(state.backoffSec * 2, 60) };
 }
+async function loadWatchHeader(onProgress) {
+    try {
+        const config = await loadConfig();
+        const state = await loadState();
+        const lastPulled = state.assets ? Object.keys(state.assets).length : 0;
+        let workingSet = 0;
+        let gameIndex;
+        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).total;
+        }
+        else if (state.synced) {
+            workingSet = Object.keys(state.synced).length;
+        }
+        return { line: formatWatchSpriteLine({ workingSet, lastPulled }), gameIndex };
+    }
+    catch {
+        return { line: null };
+    }
+}
 async function runOnce(opts, runOpts = {}) {
     const config = await loadConfig();
     const state = await loadState();
     const startedAt = new Date().toISOString();
     const concurrency = Math.max(1, Math.min(opts.concurrency ?? 6, 16));
     const verbose = !opts.quiet && !runOpts.watchMode;
+    const live = !opts.quiet;
+    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}`));
@@ -324,6 +368,8 @@ async function runOnce(opts, runOpts = {}) {
     const spinner = verbose
         ? ora(since ? `Fetching manifest since ${humanTime(since)}…` : 'Fetching manifest…').start()
         : null;
+    if (!spinner)
+        onStatus?.(since ? 'Checking MagicPixel for edits…' : 'Fetching your sprites from MagicPixel…');
     let manifest;
     try {
         manifest = await fetchAllManifest(config, since);
@@ -359,10 +405,14 @@ async function runOnce(opts, runOpts = {}) {
     // Unity projects sync only the artboards flagged "Sync to Unity" 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…');
     const projectKind = await detectProjectKind();
-    const gameIndex = isEngineKind(projectKind)
-        ? await indexGamePngs(projectKind, process.cwd(), config.outDir)
-        : { files: [], capped: false };
+    const gameIndex = runOpts.gameIndex
+        ?? (isEngineKind(projectKind)
+            ? await indexGamePngs(projectKind, process.cwd(), config.outDir, {
+                onProgress: (n) => onStatus?.(`Looking through your game sprites…  ${n.toLocaleString('en-US')}`),
+            })
+            : { files: [], capped: false });
     const connected = matchConnectGlobs(gameIndex, config.connect ?? []);
     const sourceByKey = collectSourceRelMap(connected.entries, state.synced);
     if (verbose && gameIndex.capped) {
@@ -424,7 +474,7 @@ async function runOnce(opts, runOpts = {}) {
                 bytesSaved: 0,
                 renamed: [],
             };
-            await maybePushLocalSprites(config.push, verbose, gameIndex);
+            await maybePushLocalSprites(config.push, verbose, gameIndex, live && !!runOpts.watchMode);
             return empty;
         }
         const skipped = manifest.length - filtered.entries.length;
@@ -460,6 +510,9 @@ async function runOnce(opts, runOpts = {}) {
     // the dominant wall-clock cost of an incremental sync. We cache each result
     // so the download loop can reuse it for `If-None-Match` ETags instead of
     // re-hashing the same file moments later.
+    onStatus?.(manifest.length > 0
+        ? `Comparing ${manifest.length.toLocaleString('en-US')} sprite${manifest.length === 1 ? '' : 's'} with files on disk…`
+        : 'Checking MagicPixel…');
     const diffLimit = createLimit(concurrency);
     const shaByEntryId = new Map();
     const toDownload = [];
@@ -679,7 +732,8 @@ async function runOnce(opts, runOpts = {}) {
         bytesSaved,
     };
     let progress = null;
-    if (verbose && toDownload.length > 0) {
+    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();
     }
     const run = createLimit(concurrency);
@@ -771,10 +825,15 @@ async function runOnce(opts, runOpts = {}) {
     })));
     const downloaded = result.added.length + result.modified.length;
     if (progress) {
-        if (result.failed === 0)
+        if (runOpts.watchMode) {
+            progress.stop();
+        }
+        else if (result.failed === 0) {
             progress.succeed(`Downloaded ${downloaded} (${formatBytes(result.bytesIn)})`);
-        else
+        }
+        else {
             progress.warn(`Downloaded ${downloaded}, failed ${result.failed} (${formatBytes(result.bytesIn)})`);
+        }
     }
     // Unity: write pixel-art-correct `.meta` sidecars so sprites import with
     // point filtering / no compression instead of Unity's blurry defaults —
@@ -982,21 +1041,22 @@ async function runOnce(opts, runOpts = {}) {
         if (renamed.length > 0)
             printRenames(renamed, { withHints: true });
     }
-    await maybePushLocalSprites(config.push, verbose, gameIndex);
+    onStatus?.('Checking your game files…');
+    await maybePushLocalSprites(config.push, verbose, gameIndex, live && !!runOpts.watchMode);
     if (result.failed)
         process.exitCode = 1;
     return result;
 }
-async function maybePushLocalSprites(pushEnabled, verbose, gameIndex) {
+async function maybePushLocalSprites(pushEnabled, verbose, gameIndex, announceErrors = verbose) {
     if (pushEnabled === false)
         return null;
     try {
         return await runPush({ quiet: !verbose, gameIndex });
     }
     catch (e) {
-        if (verbose) {
+        if (announceErrors) {
             console.log();
-            console.log(kleur.yellow(`! could not push working-set sprites into MagicPixel: ${e.message}`));
+            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.`));
         }
         return null;

package/dist/util/gameScan.js

@@ -94,8 +94,30 @@ function toEntry(abs, cwdAbs, assetRoot) {
         return null;
     return { abs, sourceRel, adoptRel, key: adopted.path.join('/') };
 }
+/** Spinner / status copy while walking the game tree. */
+export function countingSpritesText(found) {
+    return found > 0
+        ? `Counting sprites in your game…  ${found.toLocaleString('en-US')}`
+        : 'Counting sprites in your game…';
+}
+function bindScanProgress(onProgress) {
+    if (!onProgress)
+        return () => { };
+    let lastAt = 0;
+    let lastN = 0;
+    return (n) => {
+        if (n === lastN)
+            return;
+        const now = Date.now();
+        if (lastN === 0 || now - lastAt >= 80) {
+            lastAt = now;
+            lastN = n;
+            onProgress(n);
+        }
+    };
+}
 /** Walk the engine tree and return index entries. Does not copy files. */
-export async function indexGamePngs(kind, cwd = process.cwd(), outDir = '') {
+export async function indexGamePngs(kind, cwd = process.cwd(), outDir = '', opts = {}) {
     const empty = { files: [], capped: false };
     if (!isEngineKind(kind))
         return empty;
@@ -107,7 +129,10 @@ export async function indexGamePngs(kind, cwd = process.cwd(), outDir = '') {
     const assetRoot = namedRoot ? resolveChildDir(cwd, namedRoot) : null;
     const found = [];
     const io = createLimit(SCAN_WALK_CONCURRENCY);
-    await walkPngs(scanRoot, scanRoot, destNorm, found, MAX_GAME_INDEX + 1, io);
+    const report = bindScanProgress(opts.onProgress);
+    await walkPngs(scanRoot, scanRoot, destNorm, found, MAX_GAME_INDEX + 1, io, report);
+    if (found.length > 0)
+        opts.onProgress?.(found.length);
     found.sort((a, b) => a.localeCompare(b));
     const capped = found.length > MAX_GAME_INDEX;
     if (capped)
@@ -136,7 +161,7 @@ export function searchGameIndex(index, query) {
         return [];
     return index.files.filter((e) => e.sourceRel.toLowerCase().includes(q) || e.key.includes(q) || e.adoptRel.toLowerCase().includes(q));
 }
-async function walkPngs(dir, root, destNorm, out, limit, io) {
+async function walkPngs(dir, root, destNorm, out, limit, io, onFound) {
     if (out.length >= limit)
         return;
     let entries;
@@ -169,9 +194,10 @@ async function walkPngs(dir, root, destNorm, out, limit, io) {
         }
         else if (ent.isFile() && ent.name.toLowerCase().endsWith('.png')) {
             out.push(full);
+            onFound?.(out.length);
         }
     }
     if (subdirs.length === 0 || out.length >= limit)
         return;
-    await Promise.all(subdirs.map((d) => io(() => walkPngs(d, root, destNorm, out, limit, io))));
+    await Promise.all(subdirs.map((d) => io(() => walkPngs(d, root, destNorm, out, limit, io, onFound))));
 }

package/dist/util/watchCopy.js

@@ -0,0 +1,21 @@
+/**
+ * Watch-mode header copy. `state.assets` is only the last *successful* pull,
+ * so a connected working set of 2k sprites used to show as "Sprites: 469"
+ * while catch-up was still pending. Show both numbers when they differ.
+ */
+function fmt(n) {
+    return n.toLocaleString('en-US');
+}
+/** One header line, or null when we have nothing useful to print. */
+export function formatWatchSpriteLine(c) {
+    const set = c.workingSet > 0 ? c.workingSet : 0;
+    const pulled = c.lastPulled > 0 ? c.lastPulled : 0;
+    if (set === 0 && pulled === 0)
+        return null;
+    if (set > 0 && pulled > 0 && set !== pulled) {
+        return `   Sprites:  ${fmt(set)} in your game  ·  ${fmt(pulled)} last pulled from MagicPixel`;
+    }
+    if (set > 0)
+        return `   Sprites:  ${fmt(set)} in your working set`;
+    return `   Sprites:  ${fmt(pulled)}`;
+}

package/package.json

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