@magicpixelart/cli 0.6.1 → 0.6.3

package/CHANGELOG.md

@@ -5,6 +5,27 @@ 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
+- Merging setups cleans folder patterns (`//`, stray `~`, duplicates, ones a broader folder covers).
+- `connect` cleans typed patterns and rejects empty ones.
+- Sync warns when a hidden art folder (e.g. `.SpineRaw/rabbit`) has PNGs nothing watches, with the exact `connect` command.
+- `why` lists watched patterns once and prints a ready-to-run `connect` command.
+
+### Added
+- Upload progress shows the file's folder path (e.g. `…/rabbit/agni/ear_left_front`), not just its name.
+- "Useful commands" after `start`, "Common tasks" in `--help`, and a short hint after `sync`, all from one shared list.
+
 ## [0.6.1] - 2026-10-10
 
 ### Changed

package/README.md

@@ -102,6 +102,8 @@ No bundler config, no runtime, no extra package.
 
 ## Commands
 
+Run `magicpixel --help` for a short "Common tasks" list. A folder isn't syncing? `magicpixel why <folder>` prints the `connect` command that fixes it.
+
 | Command | What it does |
 | --- | --- |
 | `start [--force]` | One-command bootstrap. Init + login + first sync. The only command to tell new users to run. |
@@ -113,6 +115,7 @@ No bundler config, no runtime, no extra package.
 | `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. |
@@ -184,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/connect.js

@@ -4,7 +4,7 @@ import { loadConfig, saveConfig } from '../config.js';
 import { assertSafeGlob } from '../util/security.js';
 import { detectProjectKind, isEngineKind } from '../util/framework.js';
 import { describeExcluded, indexGamePngs, matchConnectGlobs, countingSpritesText } from '../util/gameScan.js';
-import { isAllSpritesGlob, nextConnectGlobs } from '../util/engineConnect.js';
+import { isAllSpritesGlob, nextConnectGlobs, normalizeConnectGlob, tidyConnectGlobs } from '../util/engineConnect.js';
 import { cmd } from '../util/invoke.js';
 import { runPush } from './push.js';
 /** Plain-language label for a connect glob (`**` is not meaningful to players). */
@@ -17,14 +17,17 @@ export function describeWorkingSet(glob) {
  * the original files — not a copy under outDir.
  */
 export async function connectCommand(glob) {
-    const pattern = assertSafeGlob(glob);
+    const pattern = normalizeConnectGlob(assertSafeGlob(glob));
+    if (!pattern)
+        throw new Error(`"${glob}" isn't a folder pattern. Example: ${cmd('connect')} 'Assets/Sprites/**'`);
     const config = await loadConfig();
-    const next = nextConnectGlobs(config.connect, pattern);
+    const next = tidyConnectGlobs(nextConnectGlobs(config.connect.map(normalizeConnectGlob), pattern));
     const changed = next.length !== config.connect.length || next.some((g, i) => g !== config.connect[i]);
     if (changed) {
+        const added = !config.connect.map(normalizeConnectGlob).includes(pattern);
         config.connect = next;
         await saveConfig(config);
-        console.log(ui.ok(`now syncing ${describeWorkingSet(pattern)}`));
+        console.log(ui.ok(added ? `now syncing ${describeWorkingSet(pattern)}` : 'tidied your folder patterns'));
     }
     const kind = await detectProjectKind();
     if (!isEngineKind(kind)) {

package/dist/commands/consolidate.js

@@ -10,6 +10,7 @@ import { readCredentialsSync, writeCredentials } from '../util/credentials.js';
 import { indexGamePngs } from '../util/gameScan.js';
 import { walkOutDirPngs } from '../util/paths.js';
 import { anchorGlob, detectWorkspaceMembers } from '../util/workspace.js';
+import { normalizeConnectGlob, tidyConnectGlobs } from '../util/engineConnect.js';
 import { detectEngineKind, readWorkspaceMembers } from '../util/framework.js';
 import { cmd } from '../util/invoke.js';
 import { ensureGitignore } from './init.js';
@@ -30,9 +31,9 @@ export function mergeSetups(members, children) {
     const configured = children.filter((c) => c.config);
     const first = configured[0]?.config ?? {};
     const uniq = (xs) => [...new Set(xs)];
-    const connect = uniq(configured.flatMap((c) => {
+    const connect = tidyConnectGlobs(configured.flatMap((c) => {
         const globs = c.config.connect?.length ? c.config.connect : ['**'];
-        return globs.map((g) => anchorGlob(c.member, g));
+        return globs.map((g) => anchorGlob(c.member, normalizeConnectGlob(g)));
     }));
     const exclude = uniq(configured.flatMap((c) => (c.config.exclude ?? []).map((g) => anchorGlob(c.member, g))));
     const include = uniq(configured.flatMap((c) => c.config.include ?? defaultConfig.include));
@@ -169,7 +170,7 @@ export async function consolidateCommand(opts = {}) {
         if (current) {
             merged.config = {
                 ...current,
-                connect: [...new Set([...(current.connect ?? []), ...merged.config.connect])],
+                connect: tidyConnectGlobs([...(current.connect ?? []), ...merged.config.connect]),
                 exclude: [...new Set([...(current.exclude ?? []), ...merged.config.exclude])],
             };
         }

package/dist/commands/push.js

@@ -7,11 +7,11 @@
  * `POST /api/public/integration/ingest`.
  */
 import kleur from 'kleur';
-import { icon, progressBar, spinner as makeSpinner, ui } from '../util/ui.js';
+import { icon, progressBar, shortenPath, spinner as makeSpinner, ui, visibleWidth } from '../util/ui.js';
 import { mkdir, readFile, rename } from 'node:fs/promises';
 import { dirname, relative, resolve } from 'node:path';
 import { loadConfig, loadState, saveState, resetStateIfProjectChanged, PROJECT_CHANGED_MESSAGE } from '../config.js';
-import { ensureEngineConnect } from '../util/engineConnect.js';
+import { ensureEngineConnect, unwatchedHiddenFolders } from '../util/engineConnect.js';
 import { PUSH_BATCH_SIZE, pushSpritesAdaptive, fetchManifestPage, getLastProjectInfo } from '../api.js';
 import { hashFile } from '../util/hash.js';
 import { createLimit } from '../util/limit.js';
@@ -80,6 +80,13 @@ export async function runPushWith(config, state, opts = {}) {
             : { files: [] });
     const matched = matchConnectGlobs(index, config.connect ?? [], config.exclude);
     const sourceByKey = collectSourceRelMap(matched.entries, state.synced);
+    if (!quiet) {
+        const watched = new Set(matched.entries.map((e) => e.key));
+        for (const [folder, n] of unwatchedHiddenFolders(index.files, watched, config.exclude ?? []).slice(0, 5)) {
+            console.log(ui.warn(`${n.toLocaleString('en-US')} PNGs in ${folder} aren't watched.`));
+            console.log(ui.fix(`${cmd('connect')} '${folder}/**'`));
+        }
+    }
     const disk = await walkOutDirPngs(config.outDir);
     const absByKey = new Map(disk.map((a) => [a.key, a.abs]));
     const entryByKey = new Map(matched.entries.map((e) => [e.key, e]));
@@ -256,10 +263,14 @@ export async function runPushWith(config, state, opts = {}) {
             });
             await saveState({ ...state, synced });
             const doneN = Math.min(i + batch.length, sprites.length);
-            if (progress)
-                progress.text = `Uploading  ${progressBar(doneN, sprites.length)}  ${kleur.dim(batch[batch.length - 1]?.name ?? '')}`;
+            const last = batch[batch.length - 1];
+            const where = last ? fpByKey.get(last.key)?.sourceRel ?? last.key : '';
+            if (progress) {
+                const head = `Uploading  ${progressBar(doneN, sprites.length)}  `;
+                progress.text = head + kleur.dim(shortenPath(where, (process.stdout.columns ?? 80) - visibleWidth(head) - 4));
+            }
             else
-                opts.onStatus?.(`${icon('up')} Uploading ${doneN}/${sprites.length} ${batch[batch.length - 1]?.name ?? ''}…`);
+                opts.onStatus?.(`${icon('up')} Uploading ${doneN}/${sprites.length} ${shortenPath(where, 60)}…`);
         }
     }
     catch (e) {

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/start.js

@@ -25,6 +25,7 @@ import { assertKeyValid } from '../util/auth.js';
 import { ApiError } from '../api.js';
 import { connectCommand } from './connect.js';
 import { isAllSpritesGlob } from '../util/engineConnect.js';
+import { COMMAND_TIPS, formatTipsBlock } from '../util/commandTips.js';
 /** Validate a key; only auth rejections map to 'rejected' — other failures throw. */
 export async function checkKey(key, config) {
     try {
@@ -215,6 +216,8 @@ export async function startCommand(opts = {}) {
     console.log();
     console.log(kleur.dim('  Game sprites write back to their original path. New MagicPixel art lands in outDir.'));
     console.log();
+    console.log(formatTipsBlock(COMMAND_TIPS.slice(1)));
+    console.log();
     if (await hasDevScript()) {
         const watchCmd = hasWatch ? 'npm run magicpixel:watch' : `${cmd('sync')} --watch`;
         console.log(kleur.dim('  Tip: run your dev server and the watcher together with'));

package/dist/commands/sync.js

@@ -1,5 +1,5 @@
 import kleur from 'kleur';
-import { canRedraw, card, fitLine, formatDuration, icon, progressBar, spinner as makeSpinner, ui } from '../util/ui.js';
+import { canRedraw, card, isPlain, fitLine, formatDuration, icon, progressBar, spinner as makeSpinner, ui } from '../util/ui.js';
 import { mkdir, unlink, readdir, rm, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { dirname, relative, resolve } from 'node:path';
@@ -28,11 +28,13 @@ 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';
 import { findForeignOwner, foreignOwnerMessage, recordProjectRoot } from '../util/projectRoots.js';
 import { placeBesideSiblings, splitStrayDownloads, straySkipMessage } from '../util/strayGuard.js';
+import { syncFooterHint } from '../util/commandTips.js';
 /** How often the watcher asks for a library "Resync from game" request. */
 const RESYNC_POLL_MS = 15_000;
 let lastResyncPollAt = 0;
@@ -1593,11 +1595,20 @@ async function runOnce(opts, runOpts = {}) {
         printChanges(result, '  ', { includeRenames: renamed.length === 0 });
         if (renamed.length > 0)
             printRenames(renamed, { withHints: true });
+        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/commands/why.js

@@ -1,5 +1,5 @@
 import kleur from 'kleur';
-import { spinner as makeSpinner } from '../util/ui.js';
+import { spinner as makeSpinner, ui } from '../util/ui.js';
 import { loadConfig, loadState } from '../config.js';
 import { detectProjectKind, isEngineKind } from '../util/framework.js';
 import { countingSpritesText, entryMatchesGlob, indexGamePngs, rootSpriteDotDirs } from '../util/gameScan.js';
@@ -27,10 +27,10 @@ export function explainSprite(entry, config, synced, currentSha) {
         return { kind: 'unchanged' };
     return { kind: 'changed', ...(typeof known.layers === 'number' ? { layers: known.layers } : {}) };
 }
-export function describeVerdict(v, config) {
+export function describeVerdict(v) {
     switch (v.kind) {
         case 'not-watched':
-            return `not watched — no "connect" pattern matches it (${(config.connect ?? []).join(', ') || 'none'}). Fix: ${cmd('connect')} '<folder>/**'`;
+            return 'not watched — no folder pattern covers it';
         case 'excluded':
             return `skipped by exclude rule "${v.rule}" — remove it from "exclude" in magicpixel.json to sync this file`;
         case 'new':
@@ -73,9 +73,13 @@ export async function whyCommand(pathArg) {
     const synced = state.synced ?? {};
     const counts = new Map();
     const lines = [];
+    let unwatched = 0;
     for (const e of files) {
         const sha = (await hashFile(e.abs))?.sha256 ?? null;
-        const text = describeVerdict(explainSprite(e, config, synced, sha), config);
+        const verdict = explainSprite(e, config, synced, sha);
+        if (verdict.kind === 'not-watched')
+            unwatched++;
+        const text = describeVerdict(verdict);
         counts.set(text, (counts.get(text) ?? 0) + 1);
         if (lines.length < 20)
             lines.push(`  ${e.sourceRel}\n    ${kleur.dim('→')} ${text}`);
@@ -88,4 +92,14 @@ export async function whyCommand(pathArg) {
     console.log(lines.join('\n'));
     if (files.length > lines.length)
         console.log(kleur.dim(`  …and ${files.length - lines.length} more`));
+    if (unwatched > 0) {
+        console.log();
+        console.log(kleur.dim(`  Watching: ${(config.connect ?? []).join(', ') || 'nothing'}`));
+        console.log(ui.fix(whyConnectCommand(files[0].sourceRel, target), '  '));
+    }
+}
+/** Ready-to-run connect command for the folder the user asked about. */
+export function whyConnectCommand(firstRel, target) {
+    const folder = firstRel.toLowerCase() === target ? firstRel.split('/').slice(0, -1).join('/') : firstRel.slice(0, target.length);
+    return `${cmd('connect')} '${folder ? `${folder}/**` : '**'}'`;
 }

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';
@@ -25,6 +26,7 @@ import { cleanStraysCommand } from './commands/cleanStrays.js';
 import { parseWatchInterval, parseConcurrency } from './util/flagValidators.js';
 import { CLI_VERSION } from './version.js';
 import { cmd } from './util/invoke.js';
+import { formatHelpTips } from './util/commandTips.js';
 // Node version guard
 const major = Number(process.versions.node.split('.')[0]);
 if (major < 18) {
@@ -54,7 +56,8 @@ const program = new Command();
 program
     .name('magicpixel')
     .description('Sync MagicPixel pixel-art assets to your local project')
-    .version(CLI_VERSION);
+    .version(CLI_VERSION)
+    .addHelpText('after', formatHelpTips());
 const wrap = (commandName, fn) => async (...args) => {
     try {
         await fn(...args);
@@ -145,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/commandTips.js

@@ -0,0 +1,33 @@
+/**
+ * Common commands shown after `start`, in `--help`, and hinted after `sync`.
+ * One list so the three places never drift apart.
+ */
+import kleur from 'kleur';
+import { cmd } from './invoke.js';
+export const COMMAND_TIPS = [
+    { run: 'sync --watch', what: 'keep sprites fresh while you work' },
+    { run: "connect '<folder>/**'", what: 'add a folder to sync (hidden ones like .SpineRaw/... too)' },
+    { run: 'sync --only <folder>', what: 'sync just one folder' },
+    { run: 'why <folder>', what: "see why files aren't uploading" },
+    { run: 'resync <folder>', what: 'local files win for one folder' },
+    { run: 'clean-strays', what: 'remove copies in the wrong place' },
+    { run: 'status', what: 'check your setup and last sync' },
+    { run: 'doctor', what: 'diagnose problems' },
+];
+const width = Math.max(...COMMAND_TIPS.map((t) => t.run.length));
+/** "Useful commands" block for the end of `start`. */
+export function formatTipsBlock(tips = COMMAND_TIPS) {
+    const prefix = cmd('').trimEnd();
+    return [
+        kleur.bold('  Useful commands'),
+        ...tips.map((t) => `    ${kleur.cyan(`${prefix} ${t.run.padEnd(width)}`)}  ${kleur.dim(t.what)}`),
+    ].join('\n');
+}
+/** "Common tasks" section for `magicpixel --help` (no colors: commander prints raw). */
+export function formatHelpTips() {
+    return ['', 'Common tasks:', ...COMMAND_TIPS.map((t) => `  $ magicpixel ${t.run.padEnd(width)}  # ${t.what}`), ''].join('\n');
+}
+/** One-line hint after a one-shot sync. */
+export function syncFooterHint() {
+    return `  Not seeing a folder? Run \`${cmd('why')} <folder>\`. All commands: \`${cmd('--help')}\`.`;
+}

package/dist/util/engineConnect.js

@@ -1,5 +1,6 @@
 import { saveConfig } from '../config.js';
 import { detectProjectKind, isEngineKind } from './framework.js';
+import { entryMatchesGlob } from './gameScan.js';
 export const DEFAULT_ENGINE_CONNECT = ['**'];
 const ALL_SPRITES_GLOBS = new Set(['**', '**/*', '**/**', '**/*.png', '**/**/*.png']);
 export function isAllSpritesGlob(glob) {
@@ -19,6 +20,44 @@ export function nextConnectGlobs(current, pattern) {
         return withoutAll;
     return [...withoutAll, pattern];
 }
+/** Clean one folder pattern: `\` → `/`, collapse `//`, drop `./`, a trailing `/` or stray `~`. */
+export function normalizeConnectGlob(glob) {
+    return glob
+        .trim()
+        .replace(/\\/g, '/')
+        .replace(/\/{2,}/g, '/')
+        .replace(/^(\.\/)+/, '')
+        .replace(/~+$/, '')
+        .replace(/\/+$/, '');
+}
+/** Normalize, dedupe, and drop patterns already covered by a broader `<folder>/**`. */
+export function tidyConnectGlobs(globs) {
+    const clean = [...new Set(globs.map(normalizeConnectGlob).filter(Boolean))];
+    const roots = clean.filter((g) => g.endsWith('/**')).map((g) => g.slice(0, -3).toLowerCase());
+    return clean.filter((g) => {
+        const base = (g.endsWith('/**') ? g.slice(0, -3) : g).toLowerCase();
+        return !roots.some((r) => r !== base && (base === r || base.startsWith(`${r}/`)))
+            && !(roots.includes(base) && !g.endsWith('/**'));
+    });
+}
+/**
+ * Hidden art folders (`<member>/.SpineRaw/<name>`) with PNGs that no pattern
+ * watches. Returns `[folder, count]`, largest first.
+ */
+export function unwatchedHiddenFolders(files, watchedKeys, exclude = [], min = 10) {
+    const counts = new Map();
+    for (const f of files) {
+        if (watchedKeys.has(f.key) || exclude.some((g) => entryMatchesGlob(f, g)))
+            continue;
+        const parts = f.sourceRel.split('/');
+        const i = parts.findIndex((p) => p.startsWith('.') && p.length > 1);
+        if (i < 0 || i + 2 >= parts.length)
+            continue;
+        const folder = parts.slice(0, i + 2).join('/');
+        counts.set(folder, (counts.get(folder) ?? 0) + 1);
+    }
+    return [...counts].filter(([, n]) => n >= min).sort((a, b) => b[1] - a[1]);
+}
 export async function ensureEngineConnect(config, cwd = process.cwd(), persist = true) {
     if (config.connect.length > 0)
         return config;

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/dist/util/ui.js

@@ -71,6 +71,25 @@ export function visibleWidth(s) {
     return w;
 }
 /** Cut a plain line to `max` visible columns. */
+/**
+ * Path that fits in `max` columns, keeping the end (the file and its parent
+ * folders) and dropping leading folders: `…/rabbit/agni/ear_left_front.png`.
+ */
+export function shortenPath(path, max) {
+    const p = path.replace(/\.png$/i, '');
+    const limit = Math.max(12, max);
+    if (p.length <= limit)
+        return p;
+    const parts = p.split('/');
+    let out = parts[parts.length - 1];
+    for (let i = parts.length - 2; i >= 0; i--) {
+        const next = `${parts[i]}/${out}`;
+        if (next.length + 2 > limit)
+            break;
+        out = next;
+    }
+    return out.length + 2 <= limit ? `…/${out}` : `…${out.slice(-(limit - 1))}`;
+}
 export function fitLine(line, columns) {
     const max = Math.max(20, (columns ?? 80) - 1);
     if (visibleWidth(line) <= max)

package/package.json

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