@magicpixelart/cli 0.5.38 → 0.6.2

package/dist/commands/logout.js

@@ -1,11 +1,12 @@
 import kleur from 'kleur';
+import { ui } from '../util/ui.js';
 import { deleteCredentials, credentialsPath } from '../util/credentials.js';
 import { relative } from 'node:path';
 export async function logoutCommand() {
     const path = credentialsPath();
     const removed = await deleteCredentials();
     if (removed) {
-        console.log(kleur.green(`✓ logged out`));
+        console.log(ui.ok(`logged out`));
         console.log(kleur.dim(`  Removed ${relative(process.cwd(), path)}.`));
     }
     else {

package/dist/commands/push.js

@@ -7,11 +7,11 @@
  * `POST /api/public/integration/ingest`.
  */
 import kleur from 'kleur';
-import ora from 'ora';
+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';
@@ -26,6 +26,19 @@ import { assertSafeIoPath } from '../util/security.js';
 const PUSH_SCAN_CONCURRENCY = 8;
 /** Paths already verified this process; hashFile still refuses a later symlink swap. */
 const verifiedIoPaths = new Set();
+/** Plain-language skip reasons for the quiet (nested-in-sync) push path. */
+export function skipIssues(legacy, flattenBlocked) {
+    return [
+        ...legacy.map((a) => ({
+            key: a.key,
+            text: 'MagicPixel file is a legacy single image — open it in MagicPixel and save once, then sync again.',
+        })),
+        ...flattenBlocked.map((a) => ({
+            key: a.key,
+            text: `MagicPixel artboard has ${a.layers ?? 'several'} layers — run \`${cmd('push')} --flatten\` to replace it with your file.`,
+        })),
+    ];
+}
 export async function pushCommand(opts = {}) {
     await runPush(opts);
 }
@@ -45,7 +58,7 @@ export async function runPush(opts = {}) {
             if (!opts.dryRun)
                 await saveState(state);
             if (!opts.quiet)
-                console.log(kleur.yellow(`! ${PROJECT_CHANGED_MESSAGE}`));
+                console.log(ui.warn(`${PROJECT_CHANGED_MESSAGE}`));
         }
     }
     return runPushWith(config, state, opts);
@@ -55,9 +68,9 @@ export async function runPushWith(config, state, opts = {}) {
     if (opts.replace)
         opts = { ...opts, flatten: true };
     const empty = {
-        created: 0, updated: 0, unchanged: 0, conflict: 0, error: 0, imported: 0, keptAssetIds: [], scanned: 0,
+        created: 0, updated: 0, unchanged: 0, conflict: 0, error: 0, imported: 0, keptAssetIds: [], scanned: 0, issues: [],
     };
-    const spinner = quiet ? null : ora(countingSpritesText(0)).start();
+    const spinner = quiet ? null : makeSpinner(countingSpritesText(0)).start();
     const kind = await detectProjectKind();
     const index = opts.gameIndex
         ?? (isEngineKind(kind)
@@ -67,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]));
@@ -90,12 +110,11 @@ export async function runPushWith(config, state, opts = {}) {
     let hashed = 0;
     const reportHash = () => {
         hashed++;
-        const n = hashed.toLocaleString('en-US');
-        const t = toHash.length.toLocaleString('en-US');
+        const line = `Checking your game files  ${progressBar(hashed, toHash.length)}`;
         if (spinner)
-            spinner.text = `Checking your game files…  ${n} / ${t}`;
+            spinner.text = line;
         else if (opts.onStatus && (hashed === 1 || hashed === toHash.length || hashed % 25 === 0)) {
-            opts.onStatus(`Checking your game files…  ${n} / ${t}`);
+            opts.onStatus(`${icon('work')} ${line}`);
         }
     };
     await Promise.all(toHash.map(([key, abs]) => scan(async () => {
@@ -149,31 +168,33 @@ export async function runPushWith(config, state, opts = {}) {
     const legacy = actions.filter((a) => a.kind === 'skip' && a.reason === 'legacy');
     const flattenBlocked = actions.filter((a) => a.kind === 'needs-flatten');
     const sendable = actions.filter((a) => a.kind === 'update' || a.kind === 'adopt');
+    const preIssues = skipIssues(legacy, flattenBlocked.map((a) => ({ key: a.key, ...('layers' in a && typeof a.layers === 'number' ? { layers: a.layers } : {}) })));
     spinner?.succeed(`Local sprites: ${candidates.length} · to push ${sendable.length} · unchanged ${skipped}` +
         (matched.entries.length ? ` · connected ${matched.entries.length}` : ''));
     if (skippedUnsafe > 0 && !quiet) {
         console.log(kleur.yellow(`! skipped ${skippedUnsafe} path${skippedUnsafe === 1 ? '' : 's'} that were not regular files inside the project.`));
     }
-    if (legacy.length > 0 && !quiet && !opts.nestedSync) {
+    if (legacy.length > 0 && !quiet) {
         console.log();
         console.log(kleur.yellow(`! ${legacy.length} sprite${legacy.length === 1 ? '' : 's'} came from a legacy single-image file — skipped.`));
-        console.log(kleur.dim(`  Fix: open the file in MagicPixel and save it once, then re-run \`${cmd('sync')}\`.`));
+        console.log(ui.fixText(`open the file in MagicPixel and save it once, then re-run \`${cmd('sync')}\`.`));
     }
-    if (flattenBlocked.length > 0 && !quiet && !opts.nestedSync) {
+    if (flattenBlocked.length > 0 && !quiet) {
         console.log();
         console.log(kleur.yellow(`! ${flattenBlocked.length} sprite${flattenBlocked.length === 1 ? '' : 's'} would flatten a multi-layer artboard — skipped.`));
         for (const a of flattenBlocked.slice(0, 10)) {
             console.log(kleur.dim(`    ${a.key} (${'layers' in a ? a.layers : '?'} layers)`));
         }
-        console.log(kleur.dim('  Fix: re-run with --flatten to replace them with the flat disk image.'));
+        console.log(ui.fixText('re-run with --flatten to replace them with the flat disk image.'));
     }
     if (sendable.length === 0) {
         await persistDiskFingerprints(state, candidates);
         if (!quiet)
-            console.log(kleur.green('✓ nothing to push.'));
+            console.log(ui.ok('nothing to push.'));
         return {
             ...empty, imported: matched.entries.length, unchanged: skipped,
             keptAssetIds: collectKeptAssetIds(candidates, state.synced ?? {}, []), scanned: candidates.length,
+            issues: preIssues, needsFlatten: flattenBlocked.map((a) => a.key), gameIndex: index,
         };
     }
     if (opts.dryRun) {
@@ -188,6 +209,7 @@ export async function runPushWith(config, state, opts = {}) {
         return {
             ...empty, imported: matched.entries.length,
             keptAssetIds: collectKeptAssetIds(candidates, state.synced ?? {}, []), scanned: candidates.length,
+            issues: preIssues, needsFlatten: flattenBlocked.map((a) => a.key), gameIndex: index,
         };
     }
     const outRoot = resolve(process.cwd(), config.outDir);
@@ -221,7 +243,8 @@ export async function runPushWith(config, state, opts = {}) {
             });
         }
     }
-    const progress = quiet ? null : ora(`Pushing 0/${sprites.length}…`).start();
+    const progress = quiet ? null : makeSpinner(`Uploading  ${progressBar(0, sprites.length)}`).start();
+    opts.onStatus?.(`${icon('up')} Uploading ${sprites.length.toLocaleString('en-US')} sprite${sprites.length === 1 ? '' : 's'}…`);
     const results = [];
     let synced = { ...(state.synced ?? {}) };
     try {
@@ -239,8 +262,15 @@ export async function runPushWith(config, state, opts = {}) {
                 outDir: config.outDir,
             });
             await saveState({ ...state, synced });
-            if (progress)
-                progress.text = `Pushing ${Math.min(i + batch.length, sprites.length)}/${sprites.length}…`;
+            const doneN = Math.min(i + batch.length, sprites.length);
+            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} ${shortenPath(where, 60)}…`);
         }
     }
     catch (e) {
@@ -300,11 +330,11 @@ export async function runPushWith(config, state, opts = {}) {
         for (const r of results) {
             if (r.status === 'conflict') {
                 if (printedIssues++ < 10)
-                    console.log(`  ${kleur.yellow('!')} ${r.key}: ${opts.force && r.lastWriteSource === 'editor' && !opts.overwriteEditorChanges ? `edited in MagicPixel — skipped. Add --overwrite-editor-changes to replace it.` : conflictHint(r.reason)}`);
+                    console.log(`  ${icon('warn')} ${r.key}: ${opts.force && r.lastWriteSource === 'editor' && !opts.overwriteEditorChanges ? `edited in MagicPixel — skipped. Add --overwrite-editor-changes to replace it.` : conflictHint(r.reason)}`);
             }
             else if (r.status === 'error') {
                 if (printedIssues++ < 10)
-                    console.log(`  ${kleur.red('!')} ${r.key}: ${r.message ?? 'push failed'}`);
+                    console.log(`  ${icon('fail')} ${r.key}: ${r.message ?? 'push failed'}`);
             }
         }
         if (printedIssues > 10)
@@ -316,9 +346,24 @@ export async function runPushWith(config, state, opts = {}) {
     }
     if (failed)
         process.exitCode = 1;
+    const issues = [...preIssues];
+    for (const r of results) {
+        if (r.status === 'conflict') {
+            issues.push({
+                key: r.key,
+                text: opts.force && r.lastWriteSource === 'editor' && !opts.overwriteEditorChanges
+                    ? 'edited in MagicPixel — skipped. Add --overwrite-editor-changes to replace it.'
+                    : conflictHint(r.reason),
+            });
+        }
+        else if (r.status === 'error') {
+            issues.push({ key: r.key, text: r.message ?? 'push failed' });
+        }
+    }
     return {
         ...counts, imported: matched.entries.length,
         keptAssetIds: collectKeptAssetIds(candidates, synced, results), scanned: candidates.length,
+        issues, needsFlatten: flattenBlocked.map((a) => a.key),
     };
 }
 /**

package/dist/commands/remove.js

@@ -1,4 +1,5 @@
 import kleur from 'kleur';
+import { ui } from '../util/ui.js';
 import { loadConfig, saveConfig } from '../config.js';
 import { assertSafeGlob } from '../util/security.js';
 export async function removeCommand(glob) {
@@ -11,5 +12,5 @@ export async function removeCommand(glob) {
         return;
     }
     await saveConfig(config);
-    console.log(kleur.green(`✓ removed include pattern: ${pattern}`));
+    console.log(ui.ok(`removed include pattern: ${pattern}`));
 }

package/dist/commands/repair.js

@@ -1,9 +1,10 @@
 import kleur from 'kleur';
+import { icon, ui } from '../util/ui.js';
 import { existsSync } from 'node:fs';
 import { rename } from 'node:fs/promises';
 import { resolve, relative } from 'node:path';
-import { createInterface } from 'node:readline/promises';
-import { stdin, stdout } from 'node:process';
+import { confirm as askYesNo } from '../util/prompt.js';
+import { stdin } from 'node:process';
 import { loadConfig, statePath, getApiKey } from '../config.js';
 import { assertKeyValid } from '../util/auth.js';
 import { listEmptyDirs, pruneEmptyDirs } from '../util/paths.js';
@@ -32,7 +33,7 @@ export async function repairCommand(opts = {}) {
     try {
         const key = getApiKey();
         await assertKeyValid(key, config);
-        console.log(`     ${kleur.green('✓')} key accepted`);
+        console.log(`     ${icon('ok')} key accepted`);
     }
     catch (e) {
         // Preserve multi-line "Fix:" guidance from getApiKey()/assertKeyValid —
@@ -40,7 +41,7 @@ export async function repairCommand(opts = {}) {
         // first-time `repair` user needs.
         const msg = e.message ?? String(e);
         const [head, ...rest] = msg.split('\n');
-        console.log(`     ${kleur.red('✗')} ${head}`);
+        console.log(`     ${icon('fail')} ${head}`);
         for (const line of rest)
             console.log(`     ${line}`);
         process.exitCode = 1;
@@ -78,10 +79,10 @@ export async function repairCommand(opts = {}) {
             const dest = `${sPath}.repair-${Date.now()}`;
             try {
                 await rename(sPath, dest);
-                console.log(`     ${kleur.green('✓')} moved to ${relative(process.cwd(), dest)}`);
+                console.log(`     ${icon('ok')} moved to ${relative(process.cwd(), dest)}`);
             }
             catch (e) {
-                console.log(`     ${kleur.red('✗')} ${e.message}`);
+                console.log(`     ${icon('fail')} ${e.message}`);
                 process.exitCode = 1;
                 return;
             }
@@ -110,7 +111,7 @@ export async function repairCommand(opts = {}) {
     }
     else {
         await pruneEmptyDirs(outRoot);
-        console.log(`     ${kleur.green('✓')} done`);
+        console.log(`     ${icon('ok')} done`);
     }
     // --- Step 4: full sync ---------------------------------------------------
     console.log(kleur.bold('4/4 ') + 'Running full sync…');
@@ -121,10 +122,10 @@ export async function repairCommand(opts = {}) {
         console.log(`     ${kleur.dim(`would run \`${cmd('sync')} --full\` (skipped in --dry-run)`)}`);
         console.log();
         if (skippedStep2) {
-            console.log(kleur.yellow('! repair plan would skip the state reset. Re-run with --yes to apply it.'));
+            console.log(ui.warn('repair plan would skip the state reset. Re-run with --yes to apply it.'));
         }
         else {
-            console.log(kleur.green('✓ repair plan looks good. Re-run without --dry-run to apply.'));
+            console.log(ui.ok('repair plan looks good. Re-run without --dry-run to apply.'));
         }
         return;
     }
@@ -138,21 +139,10 @@ export async function repairCommand(opts = {}) {
     await syncCommand({ full: true, prune: true });
     console.log();
     if ((process.exitCode ?? 0) > exitBefore) {
-        console.log(kleur.yellow(`! repair completed with errors — re-run \`${cmd('sync')}\` to retry the failed downloads.`));
+        console.log(ui.warn(`repair completed with errors — re-run \`${cmd('sync')}\` to retry the failed downloads.`));
     }
     else {
-        console.log(kleur.green('✓ repair complete.'));
-    }
-}
-async function confirm(prompt) {
-    if (!stdin.isTTY)
-        return false; // CI/non-interactive: default to NO; require --yes.
-    const rl = createInterface({ input: stdin, output: stdout });
-    try {
-        const answer = (await rl.question(`     ${prompt}`)).trim().toLowerCase();
-        return answer === 'y' || answer === 'yes';
-    }
-    finally {
-        rl.close();
+        console.log(ui.ok('repair complete.'));
     }
 }
+const confirm = (prompt) => askYesNo(`     ${prompt}`);

package/dist/commands/resync.js

@@ -7,8 +7,11 @@
  *   - MagicPixel files in that folder with no local file go to Trash.
  */
 import kleur from 'kleur';
-import { createInterface } from 'node:readline/promises';
-import { stdin, stdout } from 'node:process';
+import { ui } from '../util/ui.js';
+import { confirm } from '../util/prompt.js';
+import { canRedraw } from '../util/ui.js';
+import { stripMemberSegment } from '../util/workspace.js';
+import { stdout } from 'node:process';
 import { loadConfig, loadState } from '../config.js';
 import { ensureEngineConnect } from '../util/engineConnect.js';
 import { detectProjectKind, isEngineKind } from '../util/framework.js';
@@ -20,11 +23,11 @@ export function slugifySegment(input) {
     return input.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
 }
 export function parseFolderArg(folder) {
-    return folder
+    return stripMemberSegment(folder
         .replace(/\\/g, '/')
         .split('/')
         .map((s) => slugifySegment(s.trim()))
-        .filter(Boolean);
+        .filter(Boolean));
 }
 /**
  * True when `key` (`<folders…>/<doc>/<artboard>`) lives inside `segments`.
@@ -38,18 +41,6 @@ export function keyInFolder(key, segments) {
         return false;
     return segments.every((s, i) => folderParts[i] === s);
 }
-async function confirm(prompt) {
-    if (!stdin.isTTY)
-        return false;
-    const rl = createInterface({ input: stdin, output: stdout });
-    try {
-        const a = (await rl.question(prompt)).trim().toLowerCase();
-        return a === 'y' || a === 'yes';
-    }
-    finally {
-        rl.close();
-    }
-}
 export async function resyncCommand(folder, opts = {}) {
     await runResync(parseFolderArg(folder), opts);
 }
@@ -64,9 +55,9 @@ export async function runResync(segments, opts = {}) {
     if (!isEngineKind(kind))
         throw new Error('This folder is not a Unity/Godot/GameMaker project.');
     const gameIndex = await indexGamePngs(kind, process.cwd(), config.outDir, {
-        onProgress: opts.quiet ? undefined : (p) => { stdout.write(`\r${countingSpritesText(p)}`); },
+        onProgress: opts.quiet || !canRedraw() ? undefined : (p) => { stdout.write(`\r${countingSpritesText(p)}`); },
     });
-    if (!opts.quiet)
+    if (!opts.quiet && canRedraw())
         stdout.write('\n');
     const keyFilter = (key) => keyInFolder(key, segments);
     const label = segments.join('/');
@@ -111,8 +102,8 @@ export async function runResync(segments, opts = {}) {
         trashed = res.trashed;
     }
     if (pruneSkipped)
-        log(kleur.yellow(`! Nothing moved to Trash (${pruneSkipped}). Re-run once fixed.`));
+        log(ui.warn(`Nothing moved to Trash (${pruneSkipped}). Re-run once fixed.`));
     else
-        log(kleur.green(`✓ ${label} resynced. ${trashed} file${trashed === 1 ? '' : 's'} moved to Trash.`));
+        log(ui.ok(`${label} resynced. ${trashed} file${trashed === 1 ? '' : 's'} moved to Trash.`));
     return { push, trashed, pruneSkipped };
 }

package/dist/commands/search.js

@@ -1,5 +1,5 @@
 import kleur from 'kleur';
-import ora from 'ora';
+import { spinner as makeSpinner } from '../util/ui.js';
 import { loadConfig } from '../config.js';
 import { detectProjectKind, isEngineKind } from '../util/framework.js';
 import { indexGamePngs, searchGameIndex, countingSpritesText } from '../util/gameScan.js';
@@ -26,7 +26,7 @@ export async function searchCommand(query) {
     catch {
         // Config is optional for search — skip MagicPixel outDir when missing.
     }
-    const spinner = ora({ text: countingSpritesText(0), spinner: 'dots' }).start();
+    const spinner = makeSpinner({ text: countingSpritesText(0), spinner: 'dots' }).start();
     const index = await indexGamePngs(kind, process.cwd(), outDir, {
         onProgress: (p) => { spinner.text = countingSpritesText(p); },
     });

package/dist/commands/start.js

@@ -1,13 +1,23 @@
 import kleur from 'kleur';
+import { ui } from '../util/ui.js';
+import { confirm } from '../util/prompt.js';
+let stepNo = 0;
+let stepTotal = 0;
+const step = (title) => console.log(ui.step(++stepNo, title, stepTotal));
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { createInterface } from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
-import { resolve } from 'node:path';
+import { basename, dirname, resolve } from 'node:path';
 import { configPath, loadConfig } from '../config.js';
 import { detectProjectKind, hasPackageJson, isEngineKind } from '../util/framework.js';
 import { findKeyInDotenv, readCredentialsSync, writeCredentials } from '../util/credentials.js';
 import { initCommand } from './init.js';
+import { consolidateCommand, needsConsolidation } from './consolidate.js';
+import { cleanStraysCommand } from './cleanStrays.js';
+import { runPush } from './push.js';
+import { readWorkspaceMembers } from '../util/framework.js';
+import { detectWorkspaceMembers } from '../util/workspace.js';
 import { loginCommand } from './login.js';
 import { syncCommand } from './sync.js';
 import { cmd } from '../util/invoke.js';
@@ -15,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 {
@@ -46,6 +57,35 @@ export async function startCommand(opts = {}) {
     console.log(kleur.bold('🪄  MagicPixel — first-run setup'));
     console.log(kleur.dim('  This links your game project and syncs sprites both ways.'));
     console.log();
+    // Started inside one game folder of a monorepo: set up once at the root.
+    if (!existsSync(configPath()) && stdin.isTTY) {
+        const parent = dirname(process.cwd());
+        const siblings = detectWorkspaceMembers(parent);
+        if (siblings.length >= 2 && siblings.includes(basename(process.cwd()))) {
+            const rl = createInterface({ input: stdin, output: stdout });
+            let ans = '';
+            try {
+                ans = (await rl.question(`${kleur.cyan('?')} ${basename(process.cwd())} is one of ${siblings.length} game folders in ${parent}. Set up one MagicPixel for all of them there? ${kleur.dim('(Y/n)')} `)).trim().toLowerCase();
+            }
+            finally {
+                rl.close();
+            }
+            if (ans !== 'n' && ans !== 'no')
+                process.chdir(parent);
+        }
+    }
+    // Monorepo with several game folders: merge their old setups into one here.
+    let consolidated = false;
+    const merging = needsConsolidation();
+    stepNo = 0;
+    stepTotal = merging ? 3 : 2;
+    if (merging) {
+        step('One setup for all your game folders');
+        consolidated = await consolidateCommand({});
+        if (!consolidated && !readWorkspaceMembers(process.cwd()))
+            return;
+        console.log();
+    }
     const kind = await detectProjectKind();
     // Engine projects (including Unity UPM packages) have no package.json
     // requirement. JS projects still need one.
@@ -85,36 +125,35 @@ export async function startCommand(opts = {}) {
     const config = await loadConfig();
     const envKey = process.env.MAGICPIXEL_API_KEY?.trim();
     const stored = readCredentialsSync();
+    console.log();
+    step('Your MagicPixel account');
     if (!envKey && !stored) {
-        console.log();
-        console.log(kleur.bold('Step: connect your account'));
         await loginCommand();
     }
     else if (envKey) {
         if ((await checkKey(envKey, config)) === 'rejected') {
-            console.log(kleur.red('✖ The MAGICPIXEL_API_KEY in your environment was rejected.'));
-            console.log(kleur.dim('  Fix: set it to a fresh key from https://magicpixel.art/settings (or unset it and re-run).'));
+            console.log(ui.fail('The MAGICPIXEL_API_KEY in your environment was rejected.'));
+            console.log(ui.fix('set MAGICPIXEL_API_KEY to a fresh key from https://magicpixel.art/settings'));
             process.exitCode = 1;
             return;
         }
-        console.log(kleur.dim('  Using MAGICPIXEL_API_KEY from your environment.'));
+        console.log(ui.ok('Using MAGICPIXEL_API_KEY from your environment.'));
     }
     else if (stored && (await checkKey(stored.apiKey, config)) === 'rejected') {
-        console.log(kleur.yellow('! Your saved key was rejected (revoked, or from another account).'));
+        console.log(ui.warn('Your saved key was rejected (revoked, or from another account).'));
         if (!stdin.isTTY) {
-            console.log(kleur.dim(`  Fix: run \`${cmd('login')} --key mp_live_…\` with a fresh key from https://magicpixel.art/settings.`));
+            console.log(ui.fix(`${cmd('login')} --key mp_live_…`));
             process.exitCode = 1;
             return;
         }
-        console.log(kleur.bold('Step: connect your account'));
         await loginCommand();
     }
     else {
-        console.log(kleur.dim('  Using stored credentials from .magicpixel/credentials.'));
+        console.log(ui.ok('Signed in (saved key in .magicpixel/credentials).'));
     }
     // 4b. Don't push a whole game by surprise — offer one folder first.
     let folder = opts.folder?.trim();
-    if (!folder && shouldAskFolder(config.connect, !!stdin.isTTY, isEngineKind(kind))) {
+    if (!folder && !config.workspace && shouldAskFolder(config.connect, !!stdin.isTTY, isEngineKind(kind))) {
         const rl = createInterface({ input: stdin, output: stdout });
         try {
             folder = (await rl.question(`${kleur.cyan('?')} Sync all sprites, or one folder? ${kleur.dim('(type a folder like Sprites/Enemies, or press Enter for all)')} `)).trim();
@@ -125,7 +164,7 @@ export async function startCommand(opts = {}) {
     }
     if (folder) {
         console.log();
-        console.log(kleur.bold('Step: sync one folder'));
+        step('Sync one folder');
         await connectCommand(folderToGlob(folder));
         console.log();
         console.log(kleur.dim(`  Add another folder later with \`${cmd('connect')} "<folder>/**"\`.`));
@@ -137,11 +176,14 @@ export async function startCommand(opts = {}) {
     //    print a misleading green "you're set up" over a half-failed run.
     //    Manifest 546s throw after still importing local sprites; catch so
     //    the watch instructions below aren't swallowed.
+    if (consolidated)
+        await removeLeftoverStrays();
+    const gameIndex = await maybeFlattenLayered();
     console.log();
-    console.log(kleur.bold('Step: sync'));
+    step('First sync');
     const exitBefore = process.exitCode ?? 0;
     try {
-        await syncCommand({ full: true });
+        await syncCommand({ full: true }, { gameIndex });
     }
     catch (e) {
         const err = e;
@@ -157,7 +199,7 @@ export async function startCommand(opts = {}) {
     //    `npx` form so we never instruct users to run a script they don't have.
     console.log();
     if (firstSyncFailed) {
-        console.log(kleur.yellow('! first sync completed with errors.'));
+        console.log(ui.warn('first sync completed with errors.'));
         console.log(kleur.dim(`  Re-run \`${cmd('sync')}\` to retry the failed downloads, or \`${cmd('doctor')}\` to diagnose.`));
     }
     else {
@@ -174,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'));
@@ -181,6 +225,46 @@ export async function startCommand(opts = {}) {
         console.log();
     }
 }
+/** After a merge: drop copies an older sync wrote for another folder's sprites. */
+async function removeLeftoverStrays() {
+    try {
+        await cleanStraysCommand({ yes: true });
+    }
+    catch (e) {
+        console.log(ui.warn(`couldn't check for stray copies: ${e.message.split('\n')[0]}`));
+    }
+}
+/**
+ * Local files win: offer to replace multi-layer MagicPixel artboards that a
+ * normal upload refuses, instead of silently skipping them.
+ */
+async function maybeFlattenLayered() {
+    if (!stdin.isTTY)
+        return undefined;
+    let keys = [];
+    let gameIndex;
+    try {
+        const plan = await runPush({ dryRun: true, quiet: true, nestedSync: true });
+        keys = plan.needsFlatten ?? [];
+        gameIndex = plan.gameIndex;
+    }
+    catch {
+        return undefined;
+    }
+    if (keys.length === 0)
+        return gameIndex;
+    console.log();
+    console.log(ui.warn(`${keys.length} of your files match a MagicPixel artboard with several layers:`));
+    for (const k of keys.slice(0, 10))
+        console.log(kleur.dim(`    ${k}`));
+    if (keys.length > 10)
+        console.log(kleur.dim(`    …and ${keys.length - 10} more`));
+    if (!(await confirm(`${kleur.cyan('?')} Replace them with your local files (layers are flattened)? ${kleur.dim('(y/N)')} `)))
+        return gameIndex;
+    const only = new Set(keys);
+    await runPush({ flatten: true, keyFilter: (k) => only.has(k), gameIndex });
+    return gameIndex;
+}
 async function readPkgJson() {
     try {
         const path = resolve(process.cwd(), 'package.json');
@@ -220,7 +304,7 @@ async function maybeMigrateDotenvKey() {
         if (ans === 'n' || ans === 'no')
             return;
         await writeCredentials(found.value);
-        console.log(kleur.green(`✓ migrated key from ${found.file} → .magicpixel/credentials`));
+        console.log(ui.ok(`migrated key from ${found.file} → .magicpixel/credentials`));
         console.log(kleur.dim(`  You can now remove the MAGICPIXEL_API_KEY line from ${found.file}.`));
     }
     finally {