@magicpixelart/cli 0.5.36 → 0.6.1

package/CHANGELOG.md

@@ -5,6 +5,58 @@ 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.1] - 2026-10-10
+
+### Changed
+- Friendlier terminal: one set of icons and colors everywhere (✅ done, ⚠️ needs attention, ❌ failed, 💡 fix), numbered setup steps, a summary card after each sync, and progress bars with counts and percent.
+- `sync --watch` opens with a header card, shows ⬇️ pulled / ⬆️ sent / 🗑 removed lines, and a live "all in sync" status.
+- Errors show what happened with the fix command highlighted underneath.
+- Dry runs show a clear "Preview only — nothing changed" banner.
+- `start` numbers its steps (`1/3 · Your MagicPixel account`).
+- Checking and uploading show progress bars with the current file; the watch status line follows along (`⬆️ Uploading 4/12 body_front…`).
+- A paused watcher (offline, key or daily allowance) shows a yellow "Paused · retrying in 30s" status.
+- Errors print as a red card with the fix underneath; long lines wrap instead of being cut.
+
+### Added
+- `--plain` (also `NO_COLOR`, `MAGICPIXEL_PLAIN=1`, `CI`, `TERM=dumb`, or piped output): no colors, emoji, boxes, spinners or redraws. Errors check the error stream, so `2>errors.log` stays plain.
+
+## [0.6.0] - 2026-10-10
+
+### Added
+- Monorepo support: one `magicpixel.json` at the root (`"workspace": true`, `"members": [...]`) syncs every game folder inside it. Sprite names stay exactly as they were per folder, so nothing re-uploads.
+- `magicpixel consolidate [--dry-run] [-y]` (also run by `start` at the root) merges each game folder's old setup into one: settings and sync history are combined, `exclude`/`connect` rules re-anchored to their folder, the login key moved, old files backed up to `.magicpixel/backup/`, and stray copies of game files deleted.
+- Any command run inside a game folder of a monorepo uses the root setup, so a second one is never created. `start` inside one game folder offers to set up at the root instead.
+- New art in a game folder's library folder (e.g. a variant saved as a new file) is written next to its sibling files, in their naming style, instead of into `outDir`.
+- `start` offers to replace multi-layer MagicPixel artboards with your local files instead of skipping them.
+- Folder names typed inside a game folder (`sync --only`, `connect`, `resync`, `why`) mean that game folder, e.g. `Runtime` typed in `kr-core` is `kr-core/Runtime`.
+
+### Fixed
+- Re-running `consolidate` on a merged setup changes nothing.
+- Merge cleanup only removes empty folders and orphan `.meta` files; your own files in old output folders stay.
+
+## [0.5.39] - 2026-10-10
+
+### Fixed
+- `sync` never writes stray copies of game sprites into `outDir`. Sprites in Connected folders are written only to their real game file or beside sibling files this folder owns; the rest are skipped with one message. Works even if the owning folder never synced on this machine. `--here` still downloads copies.
+- `sync --watch` status lines fit the terminal width (no more wrapped, stacked lines), and only redraw on a live terminal.
+- `sync --watch` rescans the game tree every 5 minutes instead of every 30 seconds; edits to known files are still picked up every tick.
+- `sync --watch` now prints uploads ("Sent N edited sprites") and every sprite it could not send, with the reason (exclude rule, multi-layer artboard, legacy file, conflict). The header names any `exclude` rule that skips files.
+
+### Added
+- `magicpixel why <path>` — explains what the next sync does with each PNG under a path.
+- `magicpixel clean-strays` — removes copies a past sync wrote for sprites that belong to another game folder.
+
+## [0.5.38] - 2026-10-10
+
+### Fixed
+- Full Unity projects also scan sprite dot-folders at the project root (e.g. `.SpineRaw`), not only `Assets/`. VCS/editor folders stay skipped.
+- `sync` and `connect` report how many PNGs an `exclude` rule skipped, naming the rule.
+
+## [0.5.37] - 2026-10-09
+
+### Fixed
+- `sync` stops before writing when the sprites it would download are connected to another game folder on this machine (e.g. run from the wrong repo), naming the right folder. `--here` overrides; README documents it.
+
 ## [0.5.36] - 2026-10-07
 
 ### Changed
@@ -26,13 +78,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 ### Fixed
 - Local edits to game files that were never changed in MagicPixel no longer fail as "also changed in MagicPixel". Push now sends the cloud timestamp it last saw, and sync no longer records the local file as MagicPixel's copy when the server has no cached hash.
 
-### Changed
-- Watch header now reads "N game sprites connected" — it counts game PNGs matched by `connect`, not files waiting in MagicPixel.
-
 ## [0.5.32] - 2026-10-05
 
-### Fixed
-- `sync --watch` status lines are clipped to the terminal width, so a long sprite path no longer wraps and leaves the previous status piled on screen.
+### Changed
+- Watch header now reads "N game sprites connected" — it counts game PNGs matched by `connect`, not files waiting in MagicPixel.
 
 ## [0.5.31] - 2026-10-01
 

package/README.md

@@ -119,6 +119,8 @@ No bundler config, no runtime, no extra package.
 | `list` | Print matching manifest as a table. |
 | `status` | Config, last sync, diff vs remote. |
 | `whoami` | Verify API key, report visible assets. |
+| `why <path>` | Explain what the next sync does with each game PNG under a path (watched? excluded by which rule? new, changed, unchanged?). No network. |
+| `clean-strays [--dry-run] [-y]` | Delete copies sync wrote into `outDir` for sprites that belong to another game folder (plus their `.meta`). Never touches your own game files. |
 
 ### `sync` flags
 
@@ -131,6 +133,7 @@ No bundler config, no runtime, no extra package.
 | `-c, --concurrency <n>` | Parallel downloads (1–16, default 6). |
 | `-q, --quiet` | Minimal output (for CI). |
 | `--only <folder...>` | Only push, pull and prune inside these game folders (repeatable). Everything else is left untouched. |
+| `--here` | Download copies even if these sprites belong to another game folder. Without it, sprites from Connected folders are only written to their real game file, or beside sibling files this folder owns — never as copies under `outDir`. |
 
 Each successful sync prints a per-file change list (`+` added, `~` modified, `↪` renamed, `-` pruned) so you (and any AI agent reading the logs) know exactly what to wire up.
 
@@ -162,8 +165,29 @@ To leave game files on disk but out of your library, add them to `exclude` in `m
 { "exclude": [".SpineRaw/rabbit_nft/**"] }
 ```
 
+Sync prints how many PNGs your `exclude` rules skipped, so a forgotten rule is easy to spot. In full Unity projects sync scans `Assets/` plus sprite dot-folders at the project root (like `.SpineRaw`).
+
 Excluded files are never uploaded, even when `connect` is `**`, and the CLI never deletes them from your game. Then delete the folder in the MagicPixel library (it goes to Trash) and it stays gone.
 
+## Monorepos (several Unity projects)
+
+Keep **one** MagicPixel setup at the root of a repo that holds several game folders (e.g. `kr-core/`, `kr-remote-bundles/`):
+
+```sh
+cd my-monorepo
+npx @magicpixelart/cli@latest start      # or: magicpixel consolidate
+```
+
+- Every game folder is scanned, including hidden folders such as `.SpineRaw` (never `.git`, `Library`, `Temp`).
+- Sprite names stay the same as when each folder synced on its own — nothing re-uploads.
+- Old per-folder setups are merged, backed up to `.magicpixel/backup/`, and removed; stray copies of game files are deleted.
+- 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/**"`.
+
+## 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.
+
 ## Config (`magicpixel.json`)
 
 | Field      | Type       | Default                 | Meaning                                          |
@@ -227,6 +251,8 @@ Every error message includes a `Fix:` block. Common ones:
 | `401` / `403` | Regenerate the key at magicpixel.art/settings. |
 | `whoami` shows 0 assets | The key is bound to an empty project. Mint a key for the project that has art. |
 | `index.ts` doesn't update | Run `sync --full` once; renames may take a full pass to propagate. |
+| A file in your game isn't uploading | Run `magicpixel why <folder>` — it names the exclude rule, multi-layer artboard, or other reason. |
+| Sprites from another game appeared under `outDir` | Run `magicpixel clean-strays` to remove them, then sync from the game folder that owns them. |
 | Files keep re-downloading | Your build system is rewriting PNGs. Sync into a dir your bundler reads but doesn't mutate. |
 
 ## Telemetry

package/dist/commands/add.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 addCommand(glob) {
@@ -10,5 +11,5 @@ export async function addCommand(glob) {
     }
     config.include.push(pattern);
     await saveConfig(config);
-    console.log(kleur.green(`✓ added include pattern: ${pattern}`));
+    console.log(ui.ok(`added include pattern: ${pattern}`));
 }

package/dist/commands/cleanStrays.js

@@ -0,0 +1,92 @@
+import kleur from 'kleur';
+import { spinner as makeSpinner, ui } from '../util/ui.js';
+import { confirm } from '../util/prompt.js';
+import { existsSync } from 'node:fs';
+import { readdir, rm, rmdir } from 'node:fs/promises';
+import { dirname, relative, resolve } from 'node:path';
+import { fetchAllManifest } from '../api.js';
+import { loadConfig, loadState, saveState } from '../config.js';
+import { detectProjectKind, isEngineKind } from '../util/framework.js';
+import { countingSpritesText, indexGamePngs, matchConnectGlobs } from '../util/gameScan.js';
+import { walkOutDirPngs } from '../util/paths.js';
+import { splitStrayDownloads } from '../util/strayGuard.js';
+import { collectSourceRelMap } from '../util/syncPath.js';
+/**
+ * Copies sync wrote under outDir for game-owned sprites that have no home in
+ * this folder. Only outDir files are candidates — never a working-set original.
+ */
+export function findStrayCopies(disk, manifest, localKeys) {
+    const byKey = new Map(manifest.map((e) => [e.key, e]));
+    const candidates = disk.flatMap((d) => {
+        const m = byKey.get(d.key);
+        return m ? [{ key: d.key, game: m.game, disk: d }] : [];
+    });
+    return splitStrayDownloads(candidates, localKeys).foreign.map((c) => c.disk);
+}
+export async function removeEmptyDirsUpTo(dir, stopAt) {
+    let cur = dir;
+    while (cur.startsWith(stopAt) && cur !== stopAt) {
+        try {
+            const left = (await readdir(cur)).filter((n) => n !== '.DS_Store');
+            if (left.length > 0)
+                return;
+            await rm(resolve(cur, '.DS_Store'), { force: true });
+            await rmdir(cur);
+            await rm(`${cur}.meta`, { force: true }); // Unity folder meta
+        }
+        catch {
+            return;
+        }
+        cur = dirname(cur);
+    }
+}
+export async function cleanStraysCommand(opts = {}) {
+    const config = await loadConfig();
+    const state = await loadState();
+    const kind = await detectProjectKind();
+    const spinner = makeSpinner({ text: 'Fetching your sprites from MagicPixel…', spinner: 'dots' }).start();
+    const manifest = await fetchAllManifest(config);
+    spinner.text = countingSpritesText(0);
+    const index = isEngineKind(kind)
+        ? await indexGamePngs(kind, process.cwd(), config.outDir, {
+            onProgress: (p) => { spinner.text = countingSpritesText(p); },
+        })
+        : { files: [] };
+    const connected = matchConnectGlobs(index, config.connect ?? [], config.exclude).entries;
+    const localKeys = [...collectSourceRelMap(connected, state.synced).keys(), ...connected.map((e) => e.key)];
+    const strays = findStrayCopies(await walkOutDirPngs(config.outDir), manifest, localKeys);
+    spinner.stop();
+    if (strays.length === 0) {
+        console.log(ui.ok(`No stray copies in ${config.outDir}.`));
+        return;
+    }
+    console.log(kleur.bold(`${strays.length} stray cop${strays.length === 1 ? 'y' : 'ies'} of sprites from another game folder:`));
+    for (const s of strays.slice(0, 30))
+        console.log(`  ${kleur.red('-')} ${relative(process.cwd(), s.abs)}`);
+    if (strays.length > 30)
+        console.log(kleur.dim(`  …and ${strays.length - 30} more`));
+    console.log(kleur.dim('  Their .meta files go too. Your own game files are never touched.'));
+    if (opts.dryRun) {
+        console.log(kleur.dim('--dry-run: nothing deleted.'));
+        return;
+    }
+    if (!opts.yes && !(await confirm('Delete them? (y/N) '))) {
+        console.log(kleur.dim('Nothing deleted. Re-run with --yes to skip this question.'));
+        return;
+    }
+    const outRoot = resolve(process.cwd(), config.outDir);
+    const removedKeys = new Set();
+    for (const s of strays) {
+        await rm(s.abs, { force: true });
+        if (existsSync(`${s.abs}.meta`))
+            await rm(`${s.abs}.meta`, { force: true });
+        removedKeys.add(s.key);
+        await removeEmptyDirsUpTo(dirname(s.abs), outRoot);
+    }
+    const synced = { ...(state.synced ?? {}) };
+    for (const k of removedKeys)
+        delete synced[k];
+    const assets = Object.fromEntries(Object.entries(state.assets ?? {}).filter(([, k]) => !removedKeys.has(k)));
+    await saveState({ ...state, synced, assets });
+    console.log(ui.ok(`Removed ${removedKeys.size} stray cop${removedKeys.size === 1 ? 'y' : 'ies'}.`));
+}

package/dist/commands/connect.js

@@ -1,9 +1,9 @@
 import kleur from 'kleur';
-import ora from 'ora';
+import { spinner as makeSpinner, ui } from '../util/ui.js';
 import { loadConfig, saveConfig } from '../config.js';
 import { assertSafeGlob } from '../util/security.js';
 import { detectProjectKind, isEngineKind } from '../util/framework.js';
-import { indexGamePngs, matchConnectGlobs, countingSpritesText } from '../util/gameScan.js';
+import { describeExcluded, indexGamePngs, matchConnectGlobs, countingSpritesText } from '../util/gameScan.js';
 import { isAllSpritesGlob, nextConnectGlobs } from '../util/engineConnect.js';
 import { cmd } from '../util/invoke.js';
 import { runPush } from './push.js';
@@ -24,19 +24,22 @@ export async function connectCommand(glob) {
     if (changed) {
         config.connect = next;
         await saveConfig(config);
-        console.log(kleur.green(`✓ now syncing ${describeWorkingSet(pattern)}`));
+        console.log(ui.ok(`now syncing ${describeWorkingSet(pattern)}`));
     }
     const kind = await detectProjectKind();
     if (!isEngineKind(kind)) {
         console.log(kleur.yellow('  This folder is not a Unity/Godot/GameMaker project — nothing to ingest from disk.'));
         return;
     }
-    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(), config.outDir, {
         onProgress: (p) => { spinner.text = countingSpritesText(p); },
     });
     spinner.stop();
     const matched = matchConnectGlobs(index, config.connect, config.exclude);
+    const skipped = describeExcluded(matched);
+    if (skipped)
+        console.log(kleur.dim(`  ${skipped}`));
     if (matched.entries.length === 0) {
         console.log(kleur.yellow(`  No PNGs matched. Try \`${cmd('search')} <name>\` to see indexed paths.`));
         return;

package/dist/commands/consolidate.js

@@ -0,0 +1,308 @@
+import kleur from 'kleur';
+import { ui } from '../util/ui.js';
+import { confirm } from '../util/prompt.js';
+import { existsSync } from 'node:fs';
+import { mkdir, readdir, readFile, rename, rm, rmdir, writeFile } from 'node:fs/promises';
+import { dirname, relative, resolve } from 'node:path';
+import { stdin } from 'node:process';
+import { configPath, defaultConfig, loadState, saveConfig, saveState, } from '../config.js';
+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 { detectEngineKind, readWorkspaceMembers } from '../util/framework.js';
+import { cmd } from '../util/invoke.js';
+import { ensureGitignore } from './init.js';
+function earliest(values) {
+    return values.filter((v) => !!v).sort()[0];
+}
+/**
+ * Fold per-folder setups into one workspace setup. Globs and game paths are
+ * re-anchored at the root; sprite keys are untouched, so nothing re-uploads.
+ */
+export function mergeSetups(members, children) {
+    const projects = new Set(children.map((c) => c.state.projectId).filter((p) => !!p));
+    if (projects.size > 1) {
+        throw new Error(`These folders are linked to different MagicPixel projects:\n` +
+            children.filter((c) => c.state.projectId).map((c) => `  ${c.member}: ${c.state.projectId}`).join('\n') +
+            `\n  Fix: run \`${cmd('logout')}\` in the folder you don't want to keep, then run this again.`);
+    }
+    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 globs = c.config.connect?.length ? c.config.connect : ['**'];
+        return globs.map((g) => anchorGlob(c.member, 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));
+    const firstWithOut = configured.find((c) => typeof c.config.outDir === 'string');
+    const outDir = firstWithOut ? `${firstWithOut.member}/${firstWithOut.config.outDir}` : `${members[0]}/Assets/MagicPixel`;
+    const config = {
+        outDir,
+        include: include.length ? include : defaultConfig.include,
+        exclude,
+        connect,
+        ...(first.endpoint ? { endpoint: first.endpoint } : {}),
+        ...(first.unityPpu ? { unityPpu: first.unityPpu } : {}),
+        ...(first.push === false ? { push: false } : {}),
+        workspace: true,
+        members,
+    };
+    const synced = {};
+    const assets = {};
+    for (const c of children) {
+        for (const [k, v] of Object.entries(c.state.synced ?? {})) {
+            const next = v.sourceRel ? { ...v, sourceRel: `${c.member}/${v.sourceRel}` } : v;
+            if (!synced[k] || (!synced[k].sourceRel && next.sourceRel))
+                synced[k] = next;
+        }
+        Object.assign(assets, c.state.assets ?? {});
+    }
+    const state = {
+        synced,
+        assets,
+        ...(projects.size === 1 ? { projectId: [...projects][0] } : {}),
+        ...(earliest(children.map((c) => c.state.lastSync)) ? { lastSync: earliest(children.map((c) => c.state.lastSync)) } : {}),
+        ...(earliest(children.map((c) => c.state.lastReconcile)) ? { lastReconcile: earliest(children.map((c) => c.state.lastReconcile)) } : {}),
+    };
+    return { config, state };
+}
+/** CLI-written AGENTS.md: delete when it's only our section, else strip it. */
+export function stripAgentsSection(text) {
+    const start = text.indexOf('<!-- magicpixel:start -->');
+    const endTag = '<!-- magicpixel:end -->';
+    const end = text.indexOf(endTag);
+    if (start < 0 || end < start)
+        return text;
+    const rest = (text.slice(0, start) + text.slice(end + endTag.length)).replace(/\n{3,}/g, '\n\n').trim();
+    return rest === '' || rest === '# AGENTS' ? null : `${rest}\n`;
+}
+/** Remove `dir` and its sub-folders when they hold nothing but `.meta`/`.DS_Store` leftovers. */
+async function pruneEmptyTree(dir) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return false;
+    }
+    let empty = true;
+    for (const e of entries) {
+        const p = resolve(dir, e.name);
+        if (e.name === '.DS_Store')
+            continue;
+        if (e.isDirectory() && !e.isSymbolicLink()) {
+            if (!(await pruneEmptyTree(p)))
+                empty = false;
+        }
+        else if (e.isFile() && e.name.endsWith('.meta') && !existsSync(p.slice(0, -5))) {
+            await rm(p, { force: true }); // sidecar whose file or folder is gone
+        }
+        else if (!(e.isFile() && e.name.endsWith('.meta'))) {
+            empty = false; // any real file keeps the folder
+        }
+    }
+    if (!empty)
+        return false;
+    try {
+        const left = (await readdir(dir)).filter((n) => n !== '.DS_Store');
+        if (left.length > 0)
+            return false;
+        await rm(resolve(dir, '.DS_Store'), { force: true });
+        await rmdir(dir);
+        await rm(`${dir}.meta`, { force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readJson(path) {
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** True when this folder holds old per-game-folder setups worth merging. */
+export function needsConsolidation(root = process.cwd()) {
+    const members = readWorkspaceMembers(root);
+    if (members) {
+        return members.some((m) => existsSync(resolve(root, m, 'magicpixel.json')));
+    }
+    return detectWorkspaceMembers(root).length >= 2;
+}
+/**
+ * Merge every game folder's old setup into one at `root`, back up and remove
+ * the leftovers, and delete copies that duplicate a real game file.
+ * Returns false when the user declined or nothing was done.
+ */
+export async function consolidateCommand(opts = {}) {
+    const root = resolve(process.cwd());
+    const existing = readWorkspaceMembers(root);
+    if (!existing && existsSync(configPath(root))) {
+        throw new Error(`${root} already has its own magicpixel.json (not a monorepo setup).\n` +
+            `  Fix: move it aside and run \`${cmd('consolidate')}\` again to merge every game folder here.`);
+    }
+    const members = existing ?? detectWorkspaceMembers(root);
+    if (members.length === 0) {
+        console.log(kleur.yellow('No game folders found here. Run this in the folder that contains your Unity projects.'));
+        return false;
+    }
+    const children = [];
+    for (const member of members) {
+        const dir = resolve(root, member);
+        const config = await readJson(resolve(dir, 'magicpixel.json'));
+        const state = existsSync(resolve(dir, '.magicpixel')) ? await loadState(dir) : {};
+        children.push({ member, config, state });
+    }
+    const withSetup = children.filter((c) => c.config || Object.keys(c.state).length);
+    const merged = mergeSetups(members, children);
+    if (existing) {
+        // Re-run on an existing workspace: root records already use root-relative paths.
+        const rootState = await loadState(root);
+        merged.state.synced = { ...merged.state.synced, ...(rootState.synced ?? {}) };
+        merged.state.assets = { ...merged.state.assets, ...(rootState.assets ?? {}) };
+        const current = await readJson(configPath(root));
+        if (current) {
+            merged.config = {
+                ...current,
+                connect: [...new Set([...(current.connect ?? []), ...merged.config.connect])],
+                exclude: [...new Set([...(current.exclude ?? []), ...merged.config.exclude])],
+            };
+        }
+    }
+    // Plan the cleanup.
+    const moves = [];
+    for (const c of withSetup) {
+        const dir = resolve(root, c.member);
+        for (const name of ['magicpixel.json', 'magicpixel.json.meta', '.magicpixel']) {
+            if (existsSync(resolve(dir, name)))
+                moves.push({ from: resolve(dir, name), reason: 'old setup' });
+        }
+    }
+    const agentsEdits = [];
+    for (const c of withSetup) {
+        const path = resolve(root, c.member, 'AGENTS.md');
+        if (!existsSync(path))
+            continue;
+        const text = await readFile(path, 'utf8');
+        const next = stripAgentsSection(text);
+        if (next !== text)
+            agentsEdits.push({ path, next });
+    }
+    // Copies under a folder's old outDir that duplicate a real game file
+    // (each folder indexed on its own — same keys the workspace will use).
+    const liveKeys = new Set();
+    for (const m of members) {
+        const kind = detectEngineKind(resolve(root, m));
+        if (!kind)
+            continue;
+        (await indexGamePngs(kind, resolve(root, m), '', {})).files.forEach((f) => liveKeys.add(f.key));
+    }
+    const rootOut = resolve(root, merged.config.outDir);
+    const relocate = [];
+    for (const c of withSetup) {
+        if (typeof c.config?.outDir !== 'string')
+            continue;
+        const childOut = resolve(root, c.member, c.config.outDir);
+        if (!existsSync(childOut))
+            continue;
+        for (const d of await walkOutDirPngs(c.config.outDir, resolve(root, c.member))) {
+            if (liveKeys.has(d.key))
+                moves.push({ from: d.abs, reason: 'copy of a game file' });
+            else if (resolve(childOut) !== rootOut)
+                relocate.push({ from: d.abs, to: resolve(rootOut, relative(childOut, d.abs)) });
+        }
+    }
+    const strayCount = moves.filter((m) => m.reason === 'copy of a game file').length;
+    if (existing && moves.length === 0 && agentsEdits.length === 0 && relocate.length === 0) {
+        console.log(ui.ok('Already one MagicPixel setup here — nothing to merge.'));
+        return false;
+    }
+    // Show the plan.
+    const rel = (p) => relative(root, p) || '.';
+    console.log(kleur.bold(`One MagicPixel setup for ${rel(root) === '.' ? root : rel(root)}`));
+    console.log(`  Game folders: ${members.map((m) => (withSetup.some((c) => c.member === m) ? kleur.cyan(m) : kleur.dim(`${m} (not connected)`))).join(', ')}`);
+    console.log(`  Watching:     ${merged.config.connect.join(', ') || kleur.dim('nothing yet')}`);
+    if (merged.config.exclude.length)
+        console.log(`  Skipping:     ${merged.config.exclude.join(', ')}`);
+    console.log(`  New art goes: next to its sibling files, otherwise ${merged.config.outDir}`);
+    const oldSetups = moves.filter((m) => m.reason === 'old setup');
+    if (oldSetups.length)
+        console.log(`  Removing old setup files: ${oldSetups.map((m) => rel(m.from)).join(', ')}`);
+    if (agentsEdits.length)
+        console.log(`  Removing generated notes from: ${agentsEdits.map((a) => rel(a.path)).join(', ')}`);
+    if (strayCount)
+        console.log(`  Deleting ${strayCount} stray cop${strayCount === 1 ? 'y' : 'ies'} of game files (and their .meta)`);
+    if (relocate.length)
+        console.log(`  Moving ${relocate.length} MagicPixel-only file${relocate.length === 1 ? '' : 's'} into ${merged.config.outDir}`);
+    const unconnected = members.filter((m) => !withSetup.some((c) => c.member === m));
+    if (unconnected.length) {
+        console.log(kleur.dim(`  ${unconnected.join(', ')} stay${unconnected.length === 1 ? 's' : ''} out until you run \`${cmd('connect')} "<folder>/**"\`.`));
+    }
+    console.log(kleur.dim(`  Everything removed is backed up to .magicpixel/backup/. Your game PNGs are never touched.`));
+    if (opts.dryRun) {
+        console.log(kleur.dim('--dry-run: nothing changed.'));
+        return false;
+    }
+    if (!opts.yes && !(await confirm('Merge into one setup? (y/N) '))) {
+        console.log(kleur.dim(stdin.isTTY ? 'Nothing changed.' : 'Nothing changed. Re-run with --yes to apply.'));
+        return false;
+    }
+    // Apply. The root .magicpixel/ holds the login key and backups — keep it out of git.
+    await ensureGitignore(root);
+    // Credentials first (they live inside the .magicpixel folders we move).
+    if (!readCredentialsSync(root)) {
+        const key = withSetup.map((c) => readCredentialsSync(resolve(root, c.member))).find(Boolean)?.apiKey;
+        if (key)
+            await writeCredentials(key, root);
+    }
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const backup = resolve(root, '.magicpixel', 'backup', stamp);
+    const backupMove = async (from) => {
+        const to = resolve(backup, relative(root, from));
+        await mkdir(dirname(to), { recursive: true });
+        await rename(from, to);
+    };
+    for (const m of moves) {
+        if (!existsSync(m.from))
+            continue;
+        await backupMove(m.from);
+        if (m.reason === 'copy of a game file' && existsSync(`${m.from}.meta`))
+            await backupMove(`${m.from}.meta`);
+    }
+    for (const r of relocate) {
+        if (existsSync(r.to)) {
+            await backupMove(r.from);
+            continue;
+        }
+        await mkdir(dirname(r.to), { recursive: true });
+        await rename(r.from, r.to);
+        if (existsSync(`${r.from}.meta`))
+            await rename(`${r.from}.meta`, `${r.to}.meta`);
+    }
+    for (const c of withSetup) {
+        if (typeof c.config?.outDir !== 'string')
+            continue;
+        const childOut = resolve(root, c.member, c.config.outDir);
+        if (resolve(childOut) !== rootOut)
+            await pruneEmptyTree(childOut);
+    }
+    for (const a of agentsEdits) {
+        if (a.next === null) {
+            await backupMove(a.path);
+            if (existsSync(`${a.path}.meta`))
+                await backupMove(`${a.path}.meta`);
+        }
+        else {
+            await writeFile(a.path, a.next);
+        }
+    }
+    await saveConfig(merged.config, root);
+    await saveState(merged.state, root);
+    console.log(ui.ok(`One setup at ${root}. Run sync from here (or any game folder — it finds this one).`));
+    return true;
+}

package/dist/commands/doctor.js

@@ -1,4 +1,5 @@
 import kleur from 'kleur';
+import { icon } from '../util/ui.js';
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { resolve, relative } from 'node:path';
@@ -224,13 +225,13 @@ export function renderDoctorReport(r) {
         push(`Network probe:      ${kleur.dim(reason)}`);
     }
     else if (r.network.ok) {
-        push(`Network probe:      ${kleur.green('✓')} ${r.network.status} in ${r.network.roundtripMs}ms`);
+        push(`Network probe:      ${icon('ok')} ${r.network.status} in ${r.network.roundtripMs}ms`);
         if (r.network.requestId)
             push(`  request id:       ${kleur.dim(r.network.requestId)}`);
     }
     else {
         const statusLabel = r.network.status !== null ? `HTTP ${r.network.status}` : 'no response';
-        push(`Network probe:      ${kleur.red('✗')} ${statusLabel} (${r.network.roundtripMs}ms)`);
+        push(`Network probe:      ${icon('fail')} ${statusLabel} (${r.network.roundtripMs}ms)`);
         if (r.network.requestId)
             push(`  request id:       ${kleur.dim(r.network.requestId)}`);
         if (r.network.error)

package/dist/commands/init.js

@@ -1,4 +1,5 @@
 import kleur from 'kleur';
+import { ui } from '../util/ui.js';
 import { existsSync } from 'node:fs';
 import { readFile, appendFile, writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
@@ -79,21 +80,21 @@ export async function initCommand(opts) {
     }
     await saveConfig(config);
     console.log();
-    console.log(kleur.green('✓ wrote magicpixel.json'));
+    console.log(ui.ok('wrote magicpixel.json'));
     if (kind === 'GameMaker') {
         console.log(kleur.dim("  Note: GameMaker doesn't auto-import — refresh Included Files after each sync."));
     }
     if (addGitignore) {
         const added = await ensureGitignore();
         if (added)
-            console.log(kleur.green('✓ added .magicpixel/ to .gitignore'));
+            console.log(ui.ok('added .magicpixel/ to .gitignore'));
     }
     let watchScriptAdded = false;
     if (addWatchScript && pkgExists) {
         const r = await ensureWatchScript(pkgPath);
         watchScriptAdded = r.added;
         if (r.added)
-            console.log(kleur.green(`✓ added "${WATCH_SCRIPT_NAME}" script to package.json`));
+            console.log(ui.ok(`added "${WATCH_SCRIPT_NAME}" script to package.json`));
         else if (r.alreadyPresent)
             console.log(kleur.dim(`  "${WATCH_SCRIPT_NAME}" script already present in package.json`));
         else if (r.error)
@@ -146,8 +147,8 @@ async function ensureWatchScript(pkgPath) {
 }
 // `isImportableOutDir` lives in util/framework.ts as `isStaticOutDir`
 // (negated) — shared with `emitIndex.ts`'s AGENTS.md snippet resolver.
-async function ensureGitignore() {
-    const path = resolve(process.cwd(), '.gitignore');
+export async function ensureGitignore(cwd = process.cwd()) {
+    const path = resolve(cwd, '.gitignore');
     const marker = '.magicpixel/';
     // Accept any of these as "already ignored" so we don't append a duplicate.
     const equivalents = new Set(['.magicpixel', '.magicpixel/', '/.magicpixel', '/.magicpixel/']);

package/dist/commands/login.js

@@ -1,4 +1,5 @@
 import kleur from 'kleur';
+import { ui } from '../util/ui.js';
 import { createInterface } from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
 import { loadConfig, defaultConfig } from '../config.js';
@@ -32,7 +33,7 @@ export async function loginCommand(opts = {}) {
     }
     const path = await writeCredentials(key);
     console.log();
-    console.log(kleur.green('✓ logged in'));
+    console.log(ui.ok('logged in'));
     console.log(kleur.dim(`  Key stored at ${relative(process.cwd(), path)} (mode 0600).`));
     if (process.env.MAGICPIXEL_API_KEY) {
         console.log(kleur.yellow('  Note: MAGICPIXEL_API_KEY is still set in your environment and takes precedence.'));