@magicpixelart/cli 0.6.1 → 0.6.2

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to `@magicpixelart/cli` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.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. |

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/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';
@@ -33,6 +33,7 @@ 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,6 +1594,8 @@ 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()));
     }
     if (result.failed)
         process.exitCode = 1;

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

@@ -25,6 +25,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 +55,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);

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/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.2",
   "description": "Sync MagicPixel pixel-art assets to your local project.",
   "type": "module",
   "bin": {