@magicpixelart/cli 0.6.2 → 0.6.3

package/CHANGELOG.md

@@ -5,6 +5,15 @@ 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/).
 
+## [Unreleased]
+
+## [0.6.3] - 2026-10-17
+
+### Added
+- Spine rigs attach themselves: `sync` and `start` find Spine 4.3 skeleton exports in your game folders, match them to the synced part folders by file name, and upload them so MagicPixel shows the animated preview (e.g. `Spine rig rabbit (front, side, back) → rabbit/ (509 skins), parts fallback rabbit-pixel/`). Only changed rigs are sent; a failed upload never fails the sync.
+- `magicpixel spine [--dry-run] [--force]` runs that detection on its own and prints what it found.
+- `MAGICPIXEL_SPINE_ENDPOINT` overrides the rig upload endpoint (testing only).
+
 ## [0.6.2] - 2026-10-10
 
 ### Fixed

package/README.md

@@ -115,6 +115,7 @@ Run `magicpixel --help` for a short "Common tasks" list. A folder isn't syncing?
 | `sync [...flags]` | Two-way: pull MagicPixel edits and push changed game sprites. |
 | `push [--dry-run] [--flatten]` | Upload local PNG edits (and connected game sprites) back to MagicPixel. |
 | `resync <folder> [--dry-run] [-y]` | Local files win for one folder: overwrite MagicPixel copies, move cloud-only files to Trash. |
+| `spine [--dry-run] [--force]` | Find Spine skeleton exports and attach them to their synced part folders, so MagicPixel shows the animated preview. Also runs after every `sync`. |
 | `connect <glob>` | Limit which game folders sync (default is all sprites on Unity/Godot/GameMaker). |
 | `search <query>` | Search indexed game PNGs (no network). |
 | `add <glob>` / `remove <glob>` | Manage `include` patterns. |
@@ -186,6 +187,21 @@ npx @magicpixelart/cli@latest start      # or: magicpixel consolidate
 - Run any command from a game folder and it uses the root setup. Folder names you type are read from where you are: `sync --only Runtime` inside `kr-core` means `kr-core/Runtime`.
 - Add a folder later with `magicpixel connect "kr-puzzle/**"`.
 
+## Spine rigs (animated preview)
+
+`sync` (and `start`) look for Spine skeleton exports (`.json`, Spine 4.3) anywhere in your game folders — also in folders that aren't synced, like packed `RemoteBundleAssets` — and match them to synced folders by part file name (a `head_front` attachment ↔ `head_front.png`):
+
+```
+⬆️ Spine rig rabbit (front, side, back) → rabbit/ (509 skins), parts fallback rabbit-pixel/
+```
+
+- Skeletons in one directory that share parts (`rabbit_front/side/back.json`) become one rig with a view each.
+- A folder whose PNGs are mostly the rig's parts is a skin; when several skins sit side by side the rig is attached to their parent, so every skin gets the preview.
+- The folder outside it holding most parts (`rabbit-pixel/`) fills in parts a skin lacks.
+- Only changed rigs are uploaded (hash kept in `.magicpixel/state.json`). A failed upload only warns; sync carries on.
+
+Run `magicpixel spine --dry-run` to see what would be attached.
+
 ## Plain output
 
 Add `--plain` to any command (or set `NO_COLOR=1` or `MAGICPIXEL_PLAIN=1`) for output without colors, emoji or boxes. Piped output and CI logs are plain automatically.

package/dist/api.js

@@ -458,6 +458,31 @@ export async function pushSpritesAdaptive(sprites, retryOpts) {
         }
     }
 }
+const DEFAULT_SPINE_ENDPOINT = 'https://magicpixel.art/api/public/integration/spine';
+export function resolveSpineEndpoint() {
+    const override = process.env.MAGICPIXEL_SPINE_ENDPOINT?.trim();
+    return override ? validateEndpointUrl(override) : DEFAULT_SPINE_ENDPOINT;
+}
+/** Upload up to 10 rigs; the server attaches each to its library folder. */
+export async function pushSpineRigs(rigs, retryOpts) {
+    const url = resolveSpineEndpoint();
+    return retryTransient('spine', async () => {
+        const { headers, requestId } = buildHeaders({ 'Content-Type': 'application/json' });
+        const res = await safeFetch(url, { method: 'POST', headers, body: JSON.stringify({ rigs }) }, { timeoutMs: ASSET_TIMEOUT_MS });
+        const serverRequestId = res.headers.get('x-request-id') ?? requestId;
+        if (res.ok) {
+            const data = (await res.json());
+            const results = data && typeof data === 'object' ? data.results : undefined;
+            if (!Array.isArray(results)) {
+                throw new ApiError(502, withRequestId('spine: unexpected server response shape (results missing).', serverRequestId), serverRequestId);
+            }
+            return results;
+        }
+        const bodyText = await res.text();
+        const errorCode = errorCodeFromResponse(res);
+        throw new ApiError(res.status, withRequestId(friendlyApiError(res.status, bodyText, 'spine', errorCode), serverRequestId), serverRequestId, retryAfterMsFromResponse(res), errorCode);
+    }, retryOpts);
+}
 // ---------- folder resync (local folder is the source of truth) -------------
 export function resolveResyncEndpoint() {
     return resolveIngestEndpoint().replace(/\/ingest$/, '/resync');

package/dist/commands/spine.js

@@ -0,0 +1,187 @@
+/**
+ * `magicpixel spine` (and the tail of every `sync` / `start`): find the game's
+ * Spine skeleton exports, match them to the synced part folders, and upload
+ * them so MagicPixel's animated preview appears without attaching anything by
+ * hand. Only rigs whose skeletons or folders changed since the last upload are
+ * sent (hash remembered in `.magicpixel/state.json`).
+ */
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import kleur from 'kleur';
+import { loadConfig, loadState, saveState } from '../config.js';
+import { ApiError, pushSpineRigs } from '../api.js';
+import { detectProjectKind, isEngineKind, readWorkspaceMembers } from '../util/framework.js';
+import { indexGamePngs, matchConnectGlobs } from '../util/gameScan.js';
+import { batchRigs, describeRig, detectRigs, findSkeletonFiles, rigsToUpload, rigVersionSupported, SUPPORTED_SPINE_VERSION, syncedPngsFromEntries, } from '../util/spine.js';
+import { icon, spinner as makeSpinner, ui } from '../util/ui.js';
+/** Folders to look for skeleton exports in: each game folder of a workspace, else the setup folder. */
+export function skeletonRoots(cwd) {
+    const members = readWorkspaceMembers(cwd);
+    if (!members)
+        return [cwd];
+    const dirs = members.map((m) => resolve(cwd, m)).filter((d) => existsSync(d));
+    return dirs.length ? dirs : [cwd];
+}
+export async function runSpineRigs(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const empty = { skeletons: 0, rigs: [], skippedFiles: [] };
+    const config = opts.config ?? (await loadConfig(cwd));
+    const kind = await detectProjectKind(cwd);
+    if (!isEngineKind(kind))
+        return empty;
+    const index = opts.gameIndex ?? (await indexGamePngs(kind, cwd, config.outDir));
+    const entries = matchConnectGlobs(index, config.connect ?? [], config.exclude).entries;
+    const found = await findSkeletonFiles(skeletonRoots(cwd), cwd, [
+        resolve(cwd, config.outDir),
+        resolve(cwd, '.magicpixel'),
+    ]);
+    if (found.skeletons.length === 0)
+        return { ...empty, skippedFiles: found.skipped };
+    const rigs = entries.length ? detectRigs(found.skeletons, syncedPngsFromEntries(entries), cwd) : [];
+    const state = await loadState(cwd);
+    const pending = new Set(opts.force ? rigs : rigsToUpload(rigs, state.spineRigs));
+    const outcomes = new Map(rigs.map((rig) => [rig, { rig, status: pending.has(rig) ? 'dry-run' : 'up-to-date' }]));
+    for (const rig of pending) {
+        if (!rigVersionSupported(rig)) {
+            outcomes.set(rig, {
+                rig,
+                status: 'unsupported',
+                error: `exported from Spine ${rig.spineVersion || 'an unknown version'}; the preview reads Spine ${SUPPORTED_SPINE_VERSION} exports`,
+            });
+            pending.delete(rig);
+        }
+    }
+    if (!opts.dryRun && pending.size > 0) {
+        const upload = opts.upload ?? pushSpineRigs;
+        const record = {};
+        for (const batch of batchRigs([...pending])) {
+            try {
+                const results = await upload(batch.map((r) => ({
+                    name: r.name,
+                    folderPath: r.folderPath,
+                    baseFolderPath: r.baseFolderPath,
+                    views: r.views.map((v) => ({ name: v.name, json: v.file.json })),
+                    hash: r.hash,
+                })));
+                batch.forEach((rig, i) => {
+                    const res = results[i]?.name === rig.name ? results[i] : results.find((x) => x?.name === rig.name);
+                    const status = res?.status ?? 'error';
+                    outcomes.set(rig, { rig, status, ...(res?.error || !res ? { error: res?.error ?? 'no result from the server' } : {}) });
+                    if (status === 'saved' || status === 'unchanged')
+                        record[rig.folderPath.join('/')] = rig.hash;
+                });
+            }
+            catch (e) {
+                const message = spineErrorMessage(e);
+                for (const rig of batch)
+                    outcomes.set(rig, { rig, status: 'error', error: message });
+            }
+        }
+        if (Object.keys(record).length > 0) {
+            // Re-read: the push that just ran saved its own state.
+            const fresh = await loadState(cwd);
+            fresh.spineRigs = { ...(fresh.spineRigs ?? {}), ...record };
+            await saveState(fresh, cwd);
+        }
+    }
+    return { skeletons: found.skeletons.length, rigs: rigs.map((r) => outcomes.get(r)), skippedFiles: found.skipped };
+}
+function spineErrorMessage(e) {
+    if (e instanceof ApiError && e.status === 404)
+        return 'this MagicPixel server does not accept Spine rigs yet';
+    return (e?.message ?? String(e)).split('\n')[0];
+}
+/** One line per rig, in the CLI's status-line style. */
+export function formatSpineOutcome(o) {
+    const line = describeRig(o.rig);
+    switch (o.status) {
+        case 'saved':
+            return `${icon('up')} ${line}`;
+        case 'unchanged':
+        case 'up-to-date':
+            return `${icon('ok')} ${kleur.dim(line)}`;
+        case 'dry-run':
+            return `${icon('ghost')} ${line}`;
+        case 'missing-folder':
+            return ui.warn(`${line} — that folder isn't in MagicPixel yet`);
+        case 'unsupported':
+        case 'error':
+            return ui.warn(`${line}: ${o.error ?? 'upload failed'}`);
+    }
+}
+let warnedThisProcess = false;
+/**
+ * Sync hook: never throws. `verbose` prints every rig; otherwise only uploads
+ * and problems. A failure is reported once per process.
+ */
+export async function syncSpineRigsQuietly(opts) {
+    try {
+        const outcome = await (opts.run ?? runSpineRigs)({ config: opts.config, gameIndex: opts.gameIndex, dryRun: opts.dryRun });
+        if (opts.quiet)
+            return outcome;
+        const lines = outcome.rigs.filter((o) => {
+            if (opts.verbose)
+                return true;
+            if (o.status === 'saved')
+                return true;
+            if (o.status === 'error' || o.status === 'missing-folder' || o.status === 'unsupported') {
+                if (warnedThisProcess)
+                    return false;
+                return true;
+            }
+            return false;
+        });
+        if (lines.some((o) => o.status === 'error' || o.status === 'missing-folder' || o.status === 'unsupported')) {
+            warnedThisProcess = true;
+        }
+        if (lines.length) {
+            console.log();
+            for (const o of lines)
+                console.log(formatSpineOutcome(o));
+        }
+        return outcome;
+    }
+    catch (e) {
+        if (!opts.quiet && !warnedThisProcess) {
+            warnedThisProcess = true;
+            console.log();
+            console.log(ui.warn(`couldn't upload Spine rigs: ${spineErrorMessage(e)}`));
+        }
+        return null;
+    }
+}
+/** Test seam. */
+export function __resetSpineWarnedForTesting() {
+    warnedThisProcess = false;
+}
+export async function spineCommand(opts = {}) {
+    const spin = makeSpinner('Looking for Spine skeleton exports…').start();
+    let outcome;
+    try {
+        outcome = await runSpineRigs(opts);
+    }
+    finally {
+        spin.stop();
+    }
+    for (const f of outcome.skippedFiles)
+        console.log(ui.warn(`${f.rel}: ${f.reason}, skipped`));
+    if (outcome.skeletons === 0) {
+        console.log(`${icon('tip')} No Spine skeleton exports (.json) found in this project.`);
+        return;
+    }
+    if (outcome.rigs.length === 0) {
+        console.log(ui.warn(`Found ${outcome.skeletons} Spine skeleton${outcome.skeletons === 1 ? '' : 's'}, but no synced folder holds their part PNGs.`));
+        console.log(kleur.dim('   Parts are matched by file name (head_front.png for a "head_front" attachment).'));
+        return;
+    }
+    for (const o of outcome.rigs)
+        console.log(formatSpineOutcome(o));
+    if (opts.dryRun) {
+        console.log();
+        console.log(ui.dryRun());
+        return;
+    }
+    const failed = outcome.rigs.filter((o) => o.status === 'error' || o.status === 'missing-folder').length;
+    if (failed)
+        process.exitCode = 1;
+}

package/dist/commands/sync.js

@@ -28,6 +28,7 @@ import { canSkipWithoutHashing, decidePull, hasNewExplicitRelease } from '../uti
 import { hasUnpushedLocalEdit } from '../util/localEdit.js';
 import { shouldReconcile } from '../util/reconcile.js';
 import { runPush } from './push.js';
+import { syncSpineRigsQuietly } from './spine.js';
 import { claimResyncRequest, reportResyncRequest } from '../api.js';
 import { runResync } from './resync.js';
 import { keyInScope, pathInScope, resolveSyncScope, scopeFingerprint } from '../util/syncScope.js';
@@ -1597,10 +1598,17 @@ async function runOnce(opts, runOpts = {}) {
         if (!runOpts.watchMode && !isPlain())
             console.log(kleur.dim(syncFooterHint()));
     }
+    // Spine skeleton exports → animated preview in MagicPixel. Watchers check
+    // once per run (the scan reads every .json head); never fails the sync.
+    if (config.push !== false && (!runOpts.watchMode || !spineCheckedThisProcess)) {
+        spineCheckedThisProcess = true;
+        await syncSpineRigsQuietly({ config, gameIndex: fullGameIndex, verbose, quiet: !live });
+    }
     if (result.failed)
         process.exitCode = 1;
     return { ...result, pushed, ...(strays ? { strays } : {}) };
 }
+let spineCheckedThisProcess = false;
 async function maybePushLocalSprites(pushEnabled, verbose, gameIndex, announceErrors = verbose, onStatus, excludeKeys) {
     if (pushEnabled === false)
         return null;

package/dist/config.js

@@ -28,6 +28,7 @@ export function resetStateIfProjectChanged(state, projectId, cloudIsEmpty) {
         delete state.assets;
         delete state.manifestEtags;
         delete state.lastReconcile;
+        delete state.spineRigs;
     }
     state.projectId = projectId;
     return stale;

package/dist/index.js

@@ -16,6 +16,7 @@ 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 { spineCommand } from './commands/spine.js';
 import { searchCommand } from './commands/search.js';
 import { whyCommand } from './commands/why.js';
 import { consolidateCommand } from './commands/consolidate.js';
@@ -147,6 +148,13 @@ program
     .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(resolveInvokedPath(folder), opts)));
+program
+    .command('spine')
+    .description('Find Spine skeleton exports and attach them to their part folders in MagicPixel (also runs on every sync)')
+    .option('--dry-run', 'Show the rigs found without uploading anything')
+    .option('--force', 'Upload every rig, even ones unchanged since the last upload')
+    .addHelpText('after', '\nExamples:\n  $ magicpixel spine --dry-run\n  $ magicpixel spine\n')
+    .action(wrap("spine", async (opts) => spineCommand(opts)));
 program
     .command('connect <glob>')
     .description('Limit which game folders sync (default is all sprites)')

package/dist/util/gameScan.js

@@ -63,7 +63,7 @@ export function gameScanRoot(kind) {
             return null;
     }
 }
-function shouldSkipDir(name) {
+export function shouldSkipDir(name) {
     const n = name.toLowerCase();
     if (GAME_SCAN_SKIP_DIRS.has(n))
         return true;

package/dist/util/spine.js

@@ -0,0 +1,444 @@
+/**
+ * Spine rig auto-detection: find the game's exported skeleton JSONs, work out
+ * which synced library folders hold their part PNGs, and describe the rigs the
+ * MagicPixel preview should use.
+ *
+ * King Rabbit layout (the case this was built for):
+ *   Editor/RemoteBundleAssets/rabbit/base/rabbit_{front,side,back}.json   skeletons (not synced)
+ *   .SpineRaw/rabbit/<skin>/head_front.png …                               one folder per skin
+ *   .SpineRaw/rabbit-pixel/…                                               default parts + shadow
+ * → one rig "rabbit" with views front/side/back, bound to `rabbit/` (every
+ *   skin folder below it), with `rabbit-pixel/` supplying missing parts.
+ *
+ * Detection is pure apart from `findSkeletonFiles`, so the matching rules are
+ * unit-testable without a game tree.
+ */
+import { createHash } from 'node:crypto';
+import { open, opendir, readFile, stat } from 'node:fs/promises';
+import { basename, dirname, relative, resolve } from 'node:path';
+import { shouldSkipDir } from './gameScan.js';
+import { gameImportAdoptPath } from './pushPlan.js';
+import { createLimit } from './limit.js';
+/** The only Spine version the MagicPixel preview reads (major.minor). */
+export const SUPPORTED_SPINE_VERSION = '4.3';
+/** Server limits (see `src/lib/integration/spine.server.ts`). */
+export const MAX_SKELETON_BYTES = 8 * 1024 * 1024;
+export const MAX_VIEWS_PER_RIG = 6;
+export const MAX_RIGS_PER_REQUEST = 10;
+/** Bytes read to decide whether a .json is a skeleton export. */
+const HEAD_BYTES = 300;
+/** Stop after this many skeletons; a game with more is not what this is for. */
+const MAX_SKELETONS = 200;
+/** A folder is a skin folder when at least this share of its PNGs are rig images. */
+const SKIN_SHARE = 0.5;
+/** Base folder / view grouping need at least this share of the rig's images. */
+const COVER_SHARE = 0.5;
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** Attachment types that draw an image (no `type` means region). */
+const IMAGE_ATTACHMENTS = new Set([undefined, 'region', 'mesh', 'linkedmesh']);
+/** Cheap pre-check on the first bytes of a .json: Spine exports open with `{"skeleton":{…"spine":"4.3.23"`. */
+export function looksLikeSkeleton(head) {
+    return head.includes('"skeleton"') && head.includes('"spine"');
+}
+/** `"4.3.23"` → `"4.3"`; null when it doesn't look like a version. */
+export function spineMinorVersion(version) {
+    const m = /^(\d+)\.(\d+)/.exec(version.trim());
+    return m ? `${m[1]}.${m[2]}` : null;
+}
+function sequencePaths(path, sequence) {
+    const count = Number(sequence.count ?? 0);
+    const start = Number(sequence.start ?? 1);
+    const digits = Number(sequence.digits ?? 0);
+    const out = [];
+    for (let i = 0; i < count && i < 10_000; i++)
+        out.push(path + String(start + i).padStart(digits, '0'));
+    return out;
+}
+function skinEntries(skins) {
+    if (Array.isArray(skins))
+        return skins.filter(isObject).map((s) => (isObject(s.attachments) ? s.attachments : {}));
+    if (isObject(skins))
+        return Object.values(skins).filter(isObject);
+    return [];
+}
+/**
+ * What matching needs from a skeleton export, mirroring the app's
+ * `readSkeletonInfo` (`src/lib/spine/rig.ts`): every image any skin draws
+ * (`path ?? name ?? key`, sequences expanded). Null when it isn't a skeleton.
+ */
+export function readSkeletonImages(json) {
+    if (!isObject(json) || !isObject(json.skeleton) || !Array.isArray(json.bones))
+        return null;
+    const images = new Set();
+    for (const slots of skinEntries(json.skins)) {
+        for (const attachments of Object.values(slots)) {
+            if (!isObject(attachments))
+                continue;
+            for (const [key, attachment] of Object.entries(attachments)) {
+                if (!isObject(attachment))
+                    continue;
+                if (!IMAGE_ATTACHMENTS.has(attachment.type))
+                    continue;
+                const path = String(attachment.path ?? attachment.name ?? key);
+                if (isObject(attachment.sequence))
+                    sequencePaths(path, attachment.sequence).forEach((p) => images.add(p));
+                else
+                    images.add(path);
+            }
+        }
+    }
+    return { spineVersion: String(json.skeleton.spine ?? ''), images: [...images].sort() };
+}
+/** File-name key an image path matches: its last segment, lower-cased. */
+export function imageKey(path) {
+    return path.slice(path.lastIndexOf('/') + 1).toLowerCase();
+}
+/**
+ * Short view names: the part after the shared prefix (`rabbit_front.json`,
+ * `rabbit_side.json` → "front", "side"). Same rule as the app's `viewNames`.
+ */
+export function viewNames(fileNames) {
+    const bases = fileNames.map((f) => f.replace(/\.json$/i, ''));
+    if (bases.length < 2)
+        return bases;
+    let prefix = bases[0];
+    for (const b of bases)
+        while (!b.startsWith(prefix))
+            prefix = prefix.slice(0, -1);
+    const cut = Math.max(prefix.lastIndexOf('_'), prefix.lastIndexOf('-'), prefix.lastIndexOf('.')) + 1;
+    const names = bases.map((b) => b.slice(cut));
+    return names.every(Boolean) && new Set(names).size === names.length ? names : bases;
+}
+/** Rig name: the shared file prefix (`rabbit`), else the file / directory name. */
+export function rigName(fileNames, dirName) {
+    const bases = fileNames.map((f) => f.replace(/\.json$/i, ''));
+    if (bases.length === 1)
+        return bases[0];
+    const views = viewNames(fileNames);
+    if (views.some((v, i) => v !== bases[i]) && views.every((v, i) => bases[i].endsWith(v))) {
+        const prefix = bases[0].slice(0, bases[0].length - views[0].length).replace(/[_.-]+$/, '');
+        if (prefix)
+            return prefix;
+    }
+    return dirName;
+}
+const VIEW_ORDER = ['front', 'side', 'back'];
+function viewRank(name) {
+    const i = VIEW_ORDER.indexOf(name.toLowerCase());
+    return i === -1 ? VIEW_ORDER.length : i;
+}
+async function readHead(abs) {
+    const fh = await open(abs, 'r');
+    try {
+        const buf = Buffer.alloc(HEAD_BYTES);
+        const { bytesRead } = await fh.read(buf, 0, HEAD_BYTES, 0);
+        return buf.subarray(0, bytesRead).toString('utf8');
+    }
+    finally {
+        await fh.close();
+    }
+}
+/**
+ * Walk `roots` for Spine skeleton JSONs. Skips the same engine/VCS folders as
+ * the sprite scan (Library, Temp, node_modules, .git, …) and `skipDirs`.
+ */
+export async function findSkeletonFiles(roots, base, skipDirs = []) {
+    const skip = new Set(skipDirs.map((d) => resolve(d).replace(/\\/g, '/').toLowerCase()));
+    const io = createLimit(8);
+    const candidates = [];
+    const walk = async (dir, depth) => {
+        if (depth > 24 || skip.has(dir.replace(/\\/g, '/').toLowerCase()))
+            return;
+        const subdirs = [];
+        await io(async () => {
+            let dh;
+            try {
+                dh = await opendir(dir);
+            }
+            catch {
+                return;
+            }
+            try {
+                for await (const ent of dh) {
+                    if (ent.isSymbolicLink())
+                        continue;
+                    if (ent.isDirectory()) {
+                        if (!shouldSkipDir(ent.name))
+                            subdirs.push(resolve(dir, ent.name));
+                    }
+                    else if (ent.isFile() && ent.name.toLowerCase().endsWith('.json')) {
+                        candidates.push(resolve(dir, ent.name));
+                    }
+                }
+            }
+            catch {
+                /* unreadable mid-listing */
+            }
+        });
+        await Promise.all(subdirs.map((d) => walk(d, depth + 1)));
+    };
+    for (const root of new Set(roots.map((r) => resolve(r))))
+        await walk(root, 0);
+    candidates.sort();
+    const skeletons = [];
+    const skipped = [];
+    await Promise.all(candidates.map((abs) => io(async () => {
+        if (skeletons.length >= MAX_SKELETONS)
+            return;
+        const rel = relative(base, abs).replace(/\\/g, '/');
+        try {
+            if (!looksLikeSkeleton(await readHead(abs)))
+                return;
+            const size = (await stat(abs)).size;
+            if (size > MAX_SKELETON_BYTES) {
+                skipped.push({ rel, reason: 'larger than 8 MB' });
+                return;
+            }
+            const text = await readFile(abs, 'utf8');
+            const json = JSON.parse(text);
+            const info = readSkeletonImages(json);
+            if (!info)
+                return;
+            skeletons.push({ abs, rel, text, json, ...info });
+        }
+        catch {
+            /* not JSON after all / unreadable — not a skeleton we can use */
+        }
+    })));
+    skeletons.sort((a, b) => a.abs.localeCompare(b.abs));
+    skipped.sort((a, b) => a.rel.localeCompare(b.rel));
+    return { skeletons, skipped };
+}
+/**
+ * Library folder of each connected game PNG. Uses the same disk → library
+ * mapping as push (`gameImportAdoptPath`), so `.SpineRaw/rabbit/spider/head_front.png`
+ * lives in folder `spineraw / rabbit / spider`.
+ */
+export function syncedPngsFromEntries(entries) {
+    const out = [];
+    for (const e of entries) {
+        const adopted = gameImportAdoptPath(e.adoptRel.replace(/\.png$/i, '').split('/'));
+        const n = adopted.path.length - 2;
+        if (n < 1)
+            continue;
+        out.push({
+            folder: adopted.path.slice(0, n),
+            folderNames: adopted.pathNames.slice(0, n),
+            name: basename(e.abs).replace(/\.png$/i, '').toLowerCase(),
+        });
+    }
+    return out;
+}
+function indexFolders(pngs) {
+    const folders = new Map();
+    for (const p of pngs) {
+        const key = p.folder.join('/');
+        let f = folders.get(key);
+        if (!f)
+            folders.set(key, (f = { key, segments: p.folder, names: p.folderNames, pngs: new Set() }));
+        f.pngs.add(p.name);
+    }
+    return folders;
+}
+function countIn(set, keys) {
+    let n = 0;
+    for (const k of keys)
+        if (set.has(k))
+            n++;
+    return n;
+}
+function isInside(segments, root) {
+    return segments.length >= root.length && root.every((s, i) => segments[i] === s);
+}
+/** Groups skeletons in one directory into rigs (views of the same character). */
+export function groupSkeletons(skeletons, folders) {
+    const byDir = new Map();
+    for (const s of skeletons) {
+        const d = dirname(s.abs);
+        byDir.set(d, [...(byDir.get(d) ?? []), s]);
+    }
+    const groups = [];
+    for (const files of byDir.values()) {
+        const keys = files.map((f) => new Set(f.images.map(imageKey)));
+        const parent = files.map((_, i) => i);
+        const find = (i) => (parent[i] === i ? i : (parent[i] = find(parent[i])));
+        for (let i = 0; i < files.length; i++) {
+            for (let j = i + 1; j < files.length; j++) {
+                if (sameRig(keys[i], keys[j], folders))
+                    parent[find(i)] = find(j);
+            }
+        }
+        const byRoot = new Map();
+        files.forEach((f, i) => byRoot.set(find(i), [...(byRoot.get(find(i)) ?? []), f]));
+        groups.push(...byRoot.values());
+    }
+    return groups;
+}
+/**
+ * Two skeletons are views of one rig when their images overlap heavily, or
+ * when one synced folder holds most of both (views whose parts are named per
+ * view, `head_front` / `head_side`, still share every skin folder).
+ */
+function sameRig(a, b, folders) {
+    if (a.size === 0 || b.size === 0)
+        return false;
+    if (countIn(a, b) >= COVER_SHARE * Math.min(a.size, b.size))
+        return true;
+    for (const f of folders.values()) {
+        if (countIn(f.pngs, a) >= COVER_SHARE * a.size && countIn(f.pngs, b) >= COVER_SHARE * b.size)
+            return true;
+    }
+    return false;
+}
+export function rigHash(rig) {
+    const h = createHash('sha256');
+    h.update(JSON.stringify({
+        name: rig.name,
+        folderPath: rig.folderPath,
+        baseFolderPath: rig.baseFolderPath,
+        views: rig.views.map((v) => [v.name, createHash('sha256').update(v.text).digest('hex')]),
+    }));
+    return h.digest('hex');
+}
+const label = (names) => `${names[names.length - 1]}/`;
+/**
+ * Turns skeleton files + the synced PNGs into rigs bound to library folders.
+ * Rigs whose images match no synced folder are left out.
+ */
+export function detectRigs(skeletons, pngs, base = process.cwd()) {
+    const folders = indexFolders(pngs);
+    const rigs = [];
+    for (const group of groupSkeletons(skeletons, folders)) {
+        const files = [...group].sort((a, b) => a.abs.localeCompare(b.abs)).slice(0, MAX_VIEWS_PER_RIG);
+        const names = viewNames(files.map((f) => basename(f.abs)));
+        const views = files
+            .map((file, i) => ({ name: names[i], file }))
+            .sort((a, b) => viewRank(a.name) - viewRank(b.name) || a.name.localeCompare(b.name));
+        const keys = new Set(files.flatMap((f) => f.images.map(imageKey)));
+        if (keys.size === 0)
+            continue;
+        // Skin folders: mostly made of this rig's images.
+        const skins = [];
+        for (const f of folders.values()) {
+            const hits = countIn(f.pngs, keys);
+            if (hits > 0 && hits >= SKIN_SHARE * f.pngs.size)
+                skins.push({ f, hits });
+        }
+        if (skins.length === 0)
+            continue;
+        // Several skin folders side by side → bind to their parent (`rabbit/`).
+        const byParent = new Map();
+        for (const { f, hits } of skins) {
+            if (f.segments.length < 2)
+                continue;
+            const key = f.segments.slice(0, -1).join('/');
+            const p = byParent.get(key) ?? { segments: f.segments.slice(0, -1), names: f.names.slice(0, -1), count: 0, hits: 0 };
+            p.count++;
+            p.hits += hits;
+            byParent.set(key, p);
+        }
+        const parent = [...byParent.values()]
+            .filter((p) => p.count >= 2)
+            .sort((a, b) => b.count - a.count || b.hits - a.hits || a.segments.join('/').localeCompare(b.segments.join('/')))[0];
+        let folderPath;
+        let folderNames;
+        let skinCount;
+        if (parent) {
+            folderPath = parent.segments;
+            folderNames = parent.names;
+            skinCount = parent.count;
+        }
+        else {
+            const best = [...skins].sort((a, b) => b.hits - a.hits || a.f.key.localeCompare(b.f.key))[0];
+            folderPath = best.f.segments;
+            folderNames = best.f.names;
+            skinCount = 1;
+        }
+        // Base folder: outside the bound folder, holding the most rig images (≥ half).
+        let baseFolder = null;
+        for (const f of folders.values()) {
+            if (isInside(f.segments, folderPath))
+                continue;
+            const hits = countIn(f.pngs, keys);
+            if (!baseFolder || hits > baseFolder.hits || (hits === baseFolder.hits && f.key < baseFolder.f.key))
+                baseFolder = { f, hits };
+        }
+        if (baseFolder && baseFolder.hits < COVER_SHARE * keys.size)
+            baseFolder = null;
+        const name = rigName(files.map((f) => basename(f.abs)), basename(dirname(files[0].abs)));
+        const baseFolderPath = baseFolder?.f.segments ?? null;
+        rigs.push({
+            name,
+            dir: relative(base, dirname(files[0].abs)).replace(/\\/g, '/') || '.',
+            views,
+            spineVersion: files[0].spineVersion,
+            folderPath,
+            folderLabel: label(folderNames),
+            skins: skinCount,
+            baseFolderPath,
+            baseFolderLabel: baseFolder ? label(baseFolder.f.names) : null,
+            hash: rigHash({ name, folderPath, baseFolderPath, views: views.map((v) => ({ name: v.name, text: v.file.text })) }),
+        });
+    }
+    return onePerFolder(rigs).sort((a, b) => a.name.localeCompare(b.name) || a.folderPath.join('/').localeCompare(b.folderPath.join('/')));
+}
+/**
+ * A folder holds one rig. When several exports bind to the same folder (an
+ * old 3.8 copy next to the 4.3 one), keep the one the preview can read, then
+ * the one with the most views and images.
+ */
+function onePerFolder(rigs) {
+    const score = (r) => [
+        rigVersionSupported(r) ? 1 : 0,
+        r.views.length,
+        new Set(r.views.flatMap((v) => v.file.images)).size,
+    ];
+    const best = new Map();
+    for (const r of rigs) {
+        const key = r.folderPath.join('/');
+        const cur = best.get(key);
+        if (!cur) {
+            best.set(key, r);
+            continue;
+        }
+        const [a, b] = [score(r), score(cur)];
+        const i = a.findIndex((v, k) => v !== b[k]);
+        if (i !== -1 && a[i] > b[i])
+            best.set(key, r);
+    }
+    return [...best.values()];
+}
+/** True when the preview can read this rig's exports. */
+export function rigVersionSupported(rig) {
+    return rig.views.every((v) => spineMinorVersion(v.file.spineVersion) === SUPPORTED_SPINE_VERSION);
+}
+/** `Spine rig rabbit (front, side, back) → rabbit/ (509 skins), parts fallback rabbit-pixel/` */
+export function describeRig(rig) {
+    const views = rig.views.length > 1 || rig.views[0]?.name !== rig.name ? ` (${rig.views.map((v) => v.name).join(', ')})` : '';
+    const skins = rig.skins > 1 ? ` (${rig.skins.toLocaleString('en-US')} skins)` : '';
+    const base = rig.baseFolderLabel ? `, parts fallback ${rig.baseFolderLabel}` : '';
+    return `Spine rig ${rig.name}${views} → ${rig.folderLabel}${skins}${base}`;
+}
+/** Rigs whose hash differs from the one last uploaded for that folder. */
+export function rigsToUpload(rigs, uploaded) {
+    return rigs.filter((r) => uploaded?.[r.folderPath.join('/')] !== r.hash);
+}
+/** Batches for the upload endpoint: ≤ 10 rigs and about `maxBytes` of skeleton text each. */
+export function batchRigs(rigs, maxBytes = 16 * 1024 * 1024) {
+    const out = [];
+    let cur = [];
+    let bytes = 0;
+    for (const r of rigs) {
+        const size = r.views.reduce((n, v) => n + v.file.text.length, 0);
+        if (cur.length > 0 && (cur.length >= MAX_RIGS_PER_REQUEST || bytes + size > maxBytes)) {
+            out.push(cur);
+            cur = [];
+            bytes = 0;
+        }
+        cur.push(r);
+        bytes += size;
+    }
+    if (cur.length)
+        out.push(cur);
+    return out;
+}

package/package.json

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