@magicpixelart/cli 0.6.3 → 0.6.5

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.6.5] - 2026-10-17
+
+### Fixed
+- Spine rigs bind to the folder named like them (`bubble.json` → `bubble/`, `glyph_heart.json` → `heart/`) before falling back to matching part names, which are too generic for props (`bubble` had bound to `Environment/`, `mushrooms` to `turret/`).
+- A rig an earlier upload bound to a folder that no rig binds to now is taken off that folder, so one object's rig no longer shows on another's parts. `spine --dry-run` lists these.
+
+## [0.6.4] - 2026-10-17
+
+### Fixed
+- Spine rigs in big games: every skeleton export is scanned (0.6.3 stopped at 200, which could miss the main character's rig).
+- Only files named as views of one character (`rabbit_front`, `rabbit_side`, `rabbit_back`) become one rig; unrelated exports in the same folder no longer merge.
+- When two rigs match the same folder, the one named like the folder wins (`rabbit` over a goat that reuses the rabbit's parts).
+- Sync says when it finds Spine exports but no synced folder for them, instead of staying silent.
+
 ## [0.6.3] - 2026-10-17
 
 ### Added

package/dist/api.js

@@ -463,26 +463,37 @@ 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) {
+/** POST to the spine endpoint; returns the parsed JSON body. */
+async function postSpine(body, 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 res = await safeFetch(url, { method: 'POST', headers, body: JSON.stringify(body) }, { 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)) {
+            if (!data || typeof data !== 'object' || !Array.isArray(data.results)) {
                 throw new ApiError(502, withRequestId('spine: unexpected server response shape (results missing).', serverRequestId), serverRequestId);
             }
-            return results;
+            return data;
         }
         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);
 }
+/** Upload up to 10 rigs; the server attaches each to its library folder. */
+export async function pushSpineRigs(rigs, retryOpts) {
+    return (await postSpine({ rigs }, retryOpts)).results;
+}
+/**
+ * Take this CLI's rigs off folders it no longer binds them to. Returns the
+ * folder paths (`a/b`) the server cleared; an older server clears none.
+ */
+export async function removeSpineRigs(folderPaths, retryOpts) {
+    const data = await postSpine({ rigs: [], remove: folderPaths }, retryOpts);
+    return Array.isArray(data.removed) ? data.removed.filter((p) => typeof p === 'string') : [];
+}
 // ---------- folder resync (local folder is the source of truth) -------------
 export function resolveResyncEndpoint() {
     return resolveIngestEndpoint().replace(/\/ingest$/, '/resync');

package/dist/commands/spine.js

@@ -6,10 +6,11 @@
  * sent (hash remembered in `.magicpixel/state.json`).
  */
 import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import kleur from 'kleur';
 import { loadConfig, loadState, saveState } from '../config.js';
-import { ApiError, pushSpineRigs } from '../api.js';
+import { ApiError, pushSpineRigs, removeSpineRigs } 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';
@@ -24,7 +25,7 @@ export function skeletonRoots(cwd) {
 }
 export async function runSpineRigs(opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
-    const empty = { skeletons: 0, rigs: [], skippedFiles: [] };
+    const empty = { skeletons: 0, rigs: [], skippedFiles: [], removed: [] };
     const config = opts.config ?? (await loadConfig(cwd));
     const kind = await detectProjectKind(cwd);
     if (!isEngineKind(kind))
@@ -51,18 +52,22 @@ export async function runSpineRigs(opts = {}) {
             pending.delete(rig);
         }
     }
+    const record = {};
     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) => ({
+                const payload = await Promise.all(batch.map(async (r) => ({
                     name: r.name,
                     folderPath: r.folderPath,
                     baseFolderPath: r.baseFolderPath,
-                    views: r.views.map((v) => ({ name: v.name, json: v.file.json })),
+                    views: await Promise.all(r.views.map(async (v) => ({
+                        name: v.name,
+                        json: JSON.parse(await readFile(v.file.abs, 'utf8')),
+                    }))),
                     hash: r.hash,
                 })));
+                const results = await upload(payload);
                 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';
@@ -77,14 +82,38 @@ export async function runSpineRigs(opts = {}) {
                     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);
+    }
+    // Folders an earlier upload bound a rig to that no rig binds to now (an
+    // export was deleted, or better matching moved it): take those rigs off, so
+    // the preview doesn't show one object's rig on another's parts. Skipped when
+    // nothing was detected at all, which is more likely a broken scan.
+    const bound = new Set(rigs.map((r) => r.folderPath.join('/')));
+    const stale = rigs.length ? Object.keys(state.spineRigs ?? {}).filter((k) => !bound.has(k)) : [];
+    let removed = [];
+    if (!opts.dryRun && stale.length > 0) {
+        try {
+            removed = await (opts.remove ?? removeSpineRigs)(stale.map((k) => k.split('/')));
+        }
+        catch {
+            /* tried again next run */
         }
     }
-    return { skeletons: found.skeletons.length, rigs: rigs.map((r) => outcomes.get(r)), skippedFiles: found.skipped };
+    if (Object.keys(record).length > 0 || removed.length > 0) {
+        // Re-read: the push that just ran saved its own state.
+        const fresh = await loadState(cwd);
+        const next = { ...(fresh.spineRigs ?? {}), ...record };
+        for (const k of removed)
+            if (!bound.has(k))
+                delete next[k];
+        fresh.spineRigs = next;
+        await saveState(fresh, cwd);
+    }
+    return {
+        skeletons: found.skeletons.length,
+        rigs: rigs.map((r) => outcomes.get(r)),
+        skippedFiles: found.skipped,
+        removed: opts.dryRun ? stale : removed,
+    };
 }
 function spineErrorMessage(e) {
     if (e instanceof ApiError && e.status === 404)
@@ -119,6 +148,13 @@ export async function syncSpineRigsQuietly(opts) {
         const outcome = await (opts.run ?? runSpineRigs)({ config: opts.config, gameIndex: opts.gameIndex, dryRun: opts.dryRun });
         if (opts.quiet)
             return outcome;
+        if (outcome.skeletons > 0 && outcome.rigs.length === 0 && !warnedThisProcess) {
+            // Say why no preview appears instead of staying silent.
+            warnedThisProcess = true;
+            console.log();
+            console.log(kleur.dim(`${icon('tip')} Found ${outcome.skeletons} Spine skeleton export${outcome.skeletons === 1 ? '' : 's'}, but no synced folder holds their part PNGs. Run \`${'npx @magicpixelart/cli spine --dry-run'}\` for details.`));
+            return outcome;
+        }
         const lines = outcome.rigs.filter((o) => {
             if (opts.verbose)
                 return true;
@@ -176,6 +212,9 @@ export async function spineCommand(opts = {}) {
     }
     for (const o of outcome.rigs)
         console.log(formatSpineOutcome(o));
+    for (const k of outcome.removed) {
+        console.log(`${icon(opts.dryRun ? 'ghost' : 'ok')} ${kleur.dim(`${opts.dryRun ? 'Would take' : 'Took'} the old Spine rig off ${k}/`)}`);
+    }
     if (opts.dryRun) {
         console.log();
         console.log(ui.dryRun());

package/dist/util/spine.js

@@ -28,7 +28,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. */
@@ -183,8 +182,6 @@ export async function findSkeletonFiles(roots, base, skipDirs = []) {
     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)))
@@ -199,7 +196,8 @@ export async function findSkeletonFiles(roots, base, skipDirs = []) {
             const info = readSkeletonImages(json);
             if (!info)
                 return;
-            skeletons.push({ abs, rel, text, json, ...info });
+            // Keep only what matching needs: a big game has hundreds of exports.
+            skeletons.push({ abs, rel, sha256: createHash('sha256').update(text).digest('hex'), size, ...info });
         }
         catch {
             /* not JSON after all / unreadable — not a skeleton we can use */
@@ -250,45 +248,23 @@ function countIn(set, keys) {
 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;
-}
+/** Camera-facing suffixes that mark one view of a character (`rabbit_front.json`). */
+const VIEW_SUFFIX = /[_-](front|side|back|north|south|east|west|left|right|up|down)$/i;
 /**
- * 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).
+ * Groups skeletons into rigs. Only files in one directory whose names differ
+ * by a view suffix (`rabbit_front`, `rabbit_side`, `rabbit_back`) are views of
+ * one character; every other export is a rig of its own, even when it shares
+ * a folder or part names with others (a `Spine/` folder of unrelated props).
  */
-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;
+export function groupSkeletons(skeletons) {
+    const groups = new Map();
+    for (const s of skeletons) {
+        const stem = basename(s.abs).replace(/\.json$/i, '');
+        const character = stem.replace(VIEW_SUFFIX, '');
+        const key = character !== stem ? `${dirname(s.abs)}\0${character.toLowerCase()}` : s.abs;
+        groups.set(key, [...(groups.get(key) ?? []), s]);
     }
-    return false;
+    return [...groups.values()];
 }
 export function rigHash(rig) {
     const h = createHash('sha256');
@@ -296,11 +272,23 @@ export function rigHash(rig) {
         name: rig.name,
         folderPath: rig.folderPath,
         baseFolderPath: rig.baseFolderPath,
-        views: rig.views.map((v) => [v.name, createHash('sha256').update(v.text).digest('hex')]),
+        views: rig.views.map((v) => [v.name, v.sha256]),
     }));
     return h.digest('hex');
 }
 const label = (names) => `${names[names.length - 1]}/`;
+/** Folder-name key: `container_item`, `Container Item` and `container-item` all read `containeritem`. */
+const folderKey = (name) => name.toLowerCase().replace(/[^a-z0-9]+/g, '');
+/**
+ * Folder names a rig's parts are likely kept under, best first: the rig name,
+ * then the rig name past its first word (King Rabbit's `glyph_heart.json`
+ * draws the parts in `heart/`). Not the skeleton's directory: that is often
+ * generic (`base/`).
+ */
+export function rigFolderNames(rigName) {
+    const rest = rigName.replace(/^[^_\-. ]+[_\-. ]+/, '');
+    return [...new Set([folderKey(rigName), folderKey(rest)])].filter(Boolean);
+}
 /**
  * Turns skeleton files + the synced PNGs into rigs bound to library folders.
  * Rigs whose images match no synced folder are left out.
@@ -308,7 +296,7 @@ const label = (names) => `${names[names.length - 1]}/`;
 export function detectRigs(skeletons, pngs, base = process.cwd()) {
     const folders = indexFolders(pngs);
     const rigs = [];
-    for (const group of groupSkeletons(skeletons, folders)) {
+    for (const group of groupSkeletons(skeletons)) {
         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
@@ -317,13 +305,29 @@ export function detectRigs(skeletons, pngs, base = process.cwd()) {
         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 });
+        const name = rigName(files.map((f) => basename(f.abs)), basename(dirname(files[0].abs)));
+        // Skin folders: a folder named like the rig (or one directly below it)
+        // that holds any of its images, else folders mostly made of its images.
+        // Part names alone are too generic for props (`shadow`, `glow`, `base`):
+        // `bubble` would bind to `Environment/`, `mushrooms` to `turret/`.
+        const inFolders = (keep) => {
+            const out = [];
+            for (const f of folders.values()) {
+                const hits = countIn(f.pngs, keys);
+                if (hits > 0 && keep(f, hits))
+                    out.push({ f, hits });
+            }
+            return out;
+        };
+        let skins = [];
+        for (const key of rigFolderNames(name)) {
+            const named = (segments) => segments.length > 0 && folderKey(segments[segments.length - 1]) === key;
+            skins = inFolders((f) => named(f.segments) || named(f.segments.slice(0, -1)));
+            if (skins.length)
+                break;
         }
+        if (skins.length === 0)
+            skins = inFolders((f, hits) => hits >= SKIN_SHARE * f.pngs.size);
         if (skins.length === 0)
             continue;
         // Several skin folders side by side → bind to their parent (`rabbit/`).
@@ -365,7 +369,6 @@ export function detectRigs(skeletons, pngs, base = process.cwd()) {
         }
         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,
@@ -377,7 +380,7 @@ export function detectRigs(skeletons, pngs, base = process.cwd()) {
             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 })) }),
+            hash: rigHash({ name, folderPath, baseFolderPath, views: views.map((v) => ({ name: v.name, sha256: v.file.sha256 })) }),
         });
     }
     return onePerFolder(rigs).sort((a, b) => a.name.localeCompare(b.name) || a.folderPath.join('/').localeCompare(b.folderPath.join('/')));
@@ -385,11 +388,13 @@ export function detectRigs(skeletons, pngs, base = process.cwd()) {
 /**
  * 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.
+ * the one named like the folder, then the one with the most views and images.
  */
 function onePerFolder(rigs) {
     const score = (r) => [
         rigVersionSupported(r) ? 1 : 0,
+        // `rabbit_*.json` over a goat that reuses the rabbit's part names.
+        r.name.toLowerCase().replace(/[^a-z0-9]+/g, '-') === r.folderPath[r.folderPath.length - 1] ? 1 : 0,
         r.views.length,
         new Set(r.views.flatMap((v) => v.file.images)).size,
     ];
@@ -429,7 +434,7 @@ export function batchRigs(rigs, maxBytes = 16 * 1024 * 1024) {
     let cur = [];
     let bytes = 0;
     for (const r of rigs) {
-        const size = r.views.reduce((n, v) => n + v.file.text.length, 0);
+        const size = r.views.reduce((n, v) => n + v.file.size, 0);
         if (cur.length > 0 && (cur.length >= MAX_RIGS_PER_REQUEST || bytes + size > maxBytes)) {
             out.push(cur);
             cur = [];

package/package.json

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