@magicpixelart/cli 0.5.35 → 0.5.38

package/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to `@magicpixelart/cli` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.5.38] - 2026-10-10
+
+### Fixed
+- Full Unity projects also scan sprite dot-folders at the project root (e.g. `.SpineRaw`), not only `Assets/`. VCS/editor folders stay skipped.
+- `sync` and `connect` report how many PNGs an `exclude` rule skipped, naming the rule.
+
+## [0.5.37] - 2026-10-09
+
+### Fixed
+- `sync` stops before writing when the sprites it would download are connected to another game folder on this machine (e.g. run from the wrong repo), naming the right folder. `--here` overrides; README documents it.
+
+## [0.5.36] - 2026-10-07
+
+### Changed
+- `push --force` no longer replaces files whose newer copy was saved in the MagicPixel editor; they are listed as "edited in MagicPixel — skipped". Add `--overwrite-editor-changes` to replace them too.
+
 ## [0.5.35] - 2026-10-07
 
 ### Changed
@@ -21,13 +37,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 ### Fixed
 - Local edits to game files that were never changed in MagicPixel no longer fail as "also changed in MagicPixel". Push now sends the cloud timestamp it last saw, and sync no longer records the local file as MagicPixel's copy when the server has no cached hash.
 
-### Changed
-- Watch header now reads "N game sprites connected" — it counts game PNGs matched by `connect`, not files waiting in MagicPixel.
-
 ## [0.5.32] - 2026-10-05
 
-### Fixed
-- `sync --watch` status lines are clipped to the terminal width, so a long sprite path no longer wraps and leaves the previous status piled on screen.
+### Changed
+- Watch header now reads "N game sprites connected" — it counts game PNGs matched by `connect`, not files waiting in MagicPixel.
 
 ## [0.5.31] - 2026-10-01
 

package/README.md

@@ -131,6 +131,7 @@ No bundler config, no runtime, no extra package.
 | `-c, --concurrency <n>` | Parallel downloads (1–16, default 6). |
 | `-q, --quiet` | Minimal output (for CI). |
 | `--only <folder...>` | Only push, pull and prune inside these game folders (repeatable). Everything else is left untouched. |
+| `--here` | Download even if these sprites are connected to another game folder on this computer (sync otherwise stops and names that folder). Run sync from your game project folder. |
 
 Each successful sync prints a per-file change list (`+` added, `~` modified, `↪` renamed, `-` pruned) so you (and any AI agent reading the logs) know exactly what to wire up.
 
@@ -150,6 +151,10 @@ npx @magicpixelart/cli sync --watch --only Runtime/Sprites/Entities/decorations
 
 Only that folder is pushed, pulled, or pruned. Every other file stays exactly as it is. Repeat `--only` for more folders, or set `"syncOnly"` in `magicpixel.json`. Changing the folder list triggers one full check. `sync <folder>` without `--only` stops with an error instead of syncing everything.
 
+## Forced pushes and editor edits
+
+`push --force` keeps your local copy when a sprite changed on both sides, except for files last saved in the MagicPixel editor: those are skipped and listed, so a forced push never silently undoes editor work. Add `--overwrite-editor-changes` to replace them as well.
+
 ## Keep a folder out of MagicPixel
 
 To leave game files on disk but out of your library, add them to `exclude` in `magicpixel.json`:
@@ -158,6 +163,8 @@ To leave game files on disk but out of your library, add them to `exclude` in `m
 { "exclude": [".SpineRaw/rabbit_nft/**"] }
 ```
 
+Sync prints how many PNGs your `exclude` rules skipped, so a forgotten rule is easy to spot. In full Unity projects sync scans `Assets/` plus sprite dot-folders at the project root (like `.SpineRaw`).
+
 Excluded files are never uploaded, even when `connect` is `**`, and the CLI never deletes them from your game. Then delete the folder in the MagicPixel library (it goes to Trash) and it stays gone.
 
 ## Config (`magicpixel.json`)

package/dist/commands/connect.js

@@ -3,7 +3,7 @@ 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, countingSpritesText } from '../util/gameScan.js';
+import { describeExcluded, indexGamePngs, matchConnectGlobs, countingSpritesText } from '../util/gameScan.js';
 import { isAllSpritesGlob, nextConnectGlobs } from '../util/engineConnect.js';
 import { cmd } from '../util/invoke.js';
 import { runPush } from './push.js';
@@ -37,6 +37,9 @@ export async function connectCommand(glob) {
     });
     spinner.stop();
     const matched = matchConnectGlobs(index, config.connect, config.exclude);
+    const skipped = describeExcluded(matched);
+    if (skipped)
+        console.log(kleur.dim(`  ${skipped}`));
     if (matched.entries.length === 0) {
         console.log(kleur.yellow(`  No PNGs matched. Try \`${cmd('search')} <name>\` to see indexed paths.`));
         return;

package/dist/commands/push.js

@@ -255,7 +255,7 @@ export async function runPushWith(config, state, opts = {}) {
         // without a live sha, and the retry as an update is what makes the server
         // composite the artboard and report one.
         for (let round = 0; round < 2; round++) {
-            const retry = forcedRetrySprites(results, spriteByKey, opts.flatten === true);
+            const retry = forcedRetrySprites(results, spriteByKey, opts.flatten === true, opts.overwriteEditorChanges === true);
             if (retry.length === 0)
                 break;
             const retryResults = await pushSpritesAdaptive(retry);
@@ -300,7 +300,7 @@ export async function runPushWith(config, state, opts = {}) {
         for (const r of results) {
             if (r.status === 'conflict') {
                 if (printedIssues++ < 10)
-                    console.log(`  ${kleur.yellow('!')} ${r.key}: ${conflictHint(r.reason)}`);
+                    console.log(`  ${kleur.yellow('!')} ${r.key}: ${opts.force && r.lastWriteSource === 'editor' && !opts.overwriteEditorChanges ? `edited in MagicPixel — skipped. Add --overwrite-editor-changes to replace it.` : conflictHint(r.reason)}`);
             }
             else if (r.status === 'error') {
                 if (printedIssues++ < 10)
@@ -344,11 +344,14 @@ export function collectKeptAssetIds(candidates, synced, results) {
  * reported. Not a bypass — the server still compares, so a save that lands in
  * between refuses again.
  */
-export function forcedRetrySprites(results, spriteByKey, flatten) {
+export function forcedRetrySprites(results, spriteByKey, flatten, overwriteEditorChanges = false) {
     const out = [];
     for (const r of results) {
         if (r.status !== 'conflict' || r.reason !== 'cloud-changed' || !r.assetId)
             continue;
+        // A newer save made in the MagicPixel editor is never silently undone.
+        if (r.lastWriteSource === 'editor' && !overwriteEditorChanges)
+            continue;
         const original = spriteByKey.get(r.key);
         if (!original)
             continue;

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, 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,7 @@ 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';
 /** How often the watcher asks for a library "Resync from game" request. */
 const RESYNC_POLL_MS = 15_000;
 let lastResyncPollAt = 0;
@@ -227,7 +228,7 @@ async function watchLoop(opts) {
         const onStatus = (msg) => {
             if (opts.quiet)
                 return;
-            writeStatusLine(msg);
+            process.stdout.write(`\r\x1b[2K${kleur.dim(`${timestamp()} ${msg}`)}`);
         };
         // 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
@@ -307,7 +308,7 @@ async function watchLoop(opts) {
                 printChanges(r, /* indent */ '  ');
             }
             else {
-                writeStatusLine(`Waiting for edits… (${r.unchanged} up to date)`);
+                process.stdout.write(`\r\x1b[2K${kleur.dim(`${timestamp()} Waiting for edits… (${r.unchanged} up to date)`)}`);
             }
         }
         catch (e) {
@@ -688,6 +689,9 @@ async function runOnce(opts, runOpts = {}) {
     aliasCollisionKeys(sourceByKey, manifest.map((e) => e.key));
     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
@@ -879,6 +883,20 @@ 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;
+    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)
         : [];
@@ -1485,6 +1503,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.`));
     }
@@ -1570,11 +1593,6 @@ function progressText(done, total, bytes) {
     const bar = '█'.repeat(filled) + '░'.repeat(barWidth - filled);
     return `${bar}  ${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)}`);
-}
 function timestamp() {
     const d = new Date();
     return `[${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}:${String(d.getSeconds()).padStart(2, '0')}]`;

package/dist/index.js

@@ -94,6 +94,7 @@ program
     .option('-q, --quiet', 'Minimal output (for CI)')
     .option('-c, --concurrency <n>', 'Parallel downloads (1–16, default 6)', parseConcurrency)
     .option('--only <folder...>', 'Only sync these game folders (repeatable), e.g. Runtime/Sprites/Entities/decorations')
+    .option('--here', 'Download here even if these sprites are connected to another game folder')
     .argument('[extra...]')
     .addHelpText('after', '\nExamples:\n  $ magicpixel sync --watch --only Runtime/Sprites/Enemies   # one folder\n  $ magicpixel sync                # incremental sync\n  $ magicpixel sync --full         # ignore lastSync, re-check everything\n  $ magicpixel sync -w             # watch mode (2s; adaptive idle backoff; exit 2 after 5 auth failures)\n')
     .action(wrap("sync", async (extra, opts) => {
@@ -108,7 +109,8 @@ program
     .description('Upload local sprite edits back to MagicPixel (two-way sync)')
     .option('--dry-run', 'Print what would be pushed without sending anything')
     .option('--flatten', 'Allow replacing multi-layer artboards with the flat local image')
-    .option('--force', 'Keep your local copy when a sprite also changed in MagicPixel')
+    .option('--force', 'Keep your local copy when a sprite also changed in MagicPixel (skips files saved in the MagicPixel editor)')
+    .option('--overwrite-editor-changes', 'With --force: also replace files saved in the MagicPixel editor')
     .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

package/dist/util/gameScan.js

@@ -4,7 +4,7 @@
  * globs select a working set; sync writes back to those original paths.
  */
 import { existsSync } from 'node:fs';
-import { opendir } from 'node:fs/promises';
+import { opendir, readdir } from 'node:fs/promises';
 import { relative, resolve } from 'node:path';
 import { isEngineKind, resolveChildDir } from './framework.js';
 import { assertPathInsideRoot, sanitizeSourceRel } from './security.js';
@@ -184,6 +184,13 @@ export async function indexGamePngs(kind, cwd = process.cwd(), outDir = '', opts
     const startAt = isUnityGameProject(cwd, assetRoot) ? assetRoot : scanRoot;
     const preferFirst = startAt === scanRoot ? assetRoot : null;
     await walkPngs(startAt, scanRoot, destNorm, found, Infinity, io, report, stats, preferFirst);
+    // Full Unity games also keep sprite sources in root dot-folders next to
+    // Assets/ (e.g. `.SpineRaw`). Walk those too; Unity's own folders stay out.
+    if (startAt !== scanRoot) {
+        for (const dir of await rootSpriteDotDirs(scanRoot)) {
+            await walkPngs(dir, scanRoot, destNorm, found, Infinity, io, report, stats, null);
+        }
+    }
     report.flush?.();
     opts.onProgress?.({ pngs: found.length, folders: stats.folders });
     found.sort((a, b) => a.localeCompare(b));
@@ -195,15 +202,48 @@ export async function indexGamePngs(kind, cwd = process.cwd(), outDir = '', opts
     }
     return { files };
 }
+/** One-line summary of exclude-dropped files, or null when none. */
+export function describeExcluded(r) {
+    if (!r.excluded)
+        return null;
+    return `${r.excluded.toLocaleString('en-US')} PNG${r.excluded === 1 ? '' : 's'} skipped by exclude rules (${r.topExclude}) — edit "exclude" in magicpixel.json to include them`;
+}
+/** Root-level dot-folders that may hold sprites (not VCS/editor/tool dirs). */
+export async function rootSpriteDotDirs(root) {
+    try {
+        const ents = await readdir(root, { withFileTypes: true });
+        return ents
+            .filter((e) => e.isDirectory() && !e.isSymbolicLink() && e.name.startsWith('.') && !shouldSkipDir(e.name))
+            .map((e) => resolve(root, e.name))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
 /** Filter the index by connect globs minus exclude globs (cwd-, asset-root-relative or manifest key). */
 export function matchConnectGlobs(index, globs, exclude = []) {
     if (globs.length === 0)
         return { entries: [] };
     const hit = (e, g) => matchGlob(e.sourceRel, g) || matchGlob(e.adoptRel, g) || matchGlob(e.key, g);
     // `exclude` wins over `connect`: excluded game files are never uploaded.
-    const matched = index.files.filter((e) => globs.some((g) => hit(e, g)) && !exclude.some((g) => hit(e, g)));
+    const matched = [];
+    const byRule = new Map();
+    let excluded = 0;
+    for (const e of index.files) {
+        if (!globs.some((g) => hit(e, g)))
+            continue;
+        const rule = exclude.find((g) => hit(e, g));
+        if (rule === undefined)
+            matched.push(e);
+        else {
+            excluded++;
+            byRule.set(rule, (byRule.get(rule) ?? 0) + 1);
+        }
+    }
     matched.sort((a, b) => a.sourceRel.localeCompare(b.sourceRel));
-    return { entries: matched };
+    const topExclude = [...byRule.entries()].sort((a, b) => b[1] - a[1])[0]?.[0];
+    return { entries: matched, ...(excluded ? { excluded, topExclude } : {}) };
 }
 export function searchGameIndex(index, query) {
     const q = query.trim().toLowerCase();

package/dist/util/projectRoots.js

@@ -0,0 +1,73 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { atomicWrite } from './atomicWrite.js';
+export function registryPath(home = homedir()) {
+    return resolve(home, '.magicpixel', 'project-roots.json');
+}
+async function readRegistry(home) {
+    try {
+        const parsed = JSON.parse(await readFile(registryPath(home), 'utf8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Remember `root` as a home for this project's connected sprites. Best-effort. */
+const recorded = new Set();
+export async function recordProjectRoot(projectId, root, home) {
+    const memo = `${home ?? ''}\0${projectId}\0${resolve(root)}`;
+    if (recorded.has(memo))
+        return; // watch mode: once per run
+    recorded.add(memo);
+    try {
+        const reg = await readRegistry(home);
+        const abs = resolve(root);
+        const list = reg[projectId] ?? [];
+        if (list.includes(abs))
+            return;
+        reg[projectId] = [...list, abs].slice(-20);
+        const path = registryPath(home);
+        await mkdir(dirname(path), { recursive: true });
+        await atomicWrite(path, JSON.stringify(reg, null, 2));
+    }
+    catch {
+        /* registry is advisory */
+    }
+}
+/** Keys another folder already syncs to a real game path. */
+function connectedKeysAt(root) {
+    try {
+        const state = JSON.parse(readFileSync(resolve(root, '.magicpixel', 'state.json'), 'utf8'));
+        return new Set(Object.entries(state.synced ?? {}).filter(([, v]) => !!v?.sourceRel).map(([k]) => k));
+    }
+    catch {
+        return new Set();
+    }
+}
+/**
+ * Of the keys this run would download WITHOUT a local game path, how many
+ * belong to another registered folder. Returns the folder owning the most, or
+ * null when the download is safe.
+ */
+export async function findForeignOwner(projectId, cwd, downloadKeysWithoutLocalPath, home) {
+    if (downloadKeysWithoutLocalPath.length === 0)
+        return null;
+    const here = resolve(cwd);
+    const roots = ((await readRegistry(home))[projectId] ?? []).filter((r) => r !== here && existsSync(r));
+    let best = null;
+    for (const root of roots) {
+        const owned = connectedKeysAt(root);
+        const count = downloadKeysWithoutLocalPath.filter((k) => owned.has(k)).length;
+        if (count > 0 && (!best || count > best.count))
+            best = { root, count };
+    }
+    return best;
+}
+export function foreignOwnerMessage(owner, cwd, rerun) {
+    return (`This folder isn't the game these sprites are connected to.\n` +
+        `  ${owner.count} sprite${owner.count === 1 ? '' : 's'} live in ${owner.root}, not ${resolve(cwd)}.\n` +
+        `  Fix: cd "${owner.root}" and run sync there — or ${rerun} to download copies here anyway.`);
+}

package/dist/util/watchCopy.js

@@ -39,19 +39,3 @@ export function formatSlowTickLine(elapsedSec, lastStatus) {
         ? `${what} — still working (${elapsed})`
         : `Still working (${elapsed})`;
 }
-/**
- * Fit a carriage-return status line to one terminal row. `\r\x1b[2K` only
- * clears the row the cursor is on, so a line that wraps leaves its first rows
- * behind and the next status prints after them (long "Looking through your
- * game sprites… <folder>" lines piled up this way). No width (not a TTY) →
- * unchanged.
- */
-export function fitStatusLine(line, columns) {
-    if (!columns || columns < 2)
-        return line;
-    const max = columns - 1; // leave the last cell free so the cursor can't wrap
-    const chars = Array.from(line);
-    if (chars.length <= max)
-        return line;
-    return `${chars.slice(0, max - 1).join('')}…`;
-}

package/package.json

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