@magicpixelart/cli 0.5.38 → 0.6.1

package/dist/index.js

@@ -17,6 +17,11 @@ import { startCommand } from './commands/start.js';
 import { connectCommand } from './commands/connect.js';
 import { resyncCommand } from './commands/resync.js';
 import { searchCommand } from './commands/search.js';
+import { whyCommand } from './commands/why.js';
+import { consolidateCommand } from './commands/consolidate.js';
+import { findWorkspaceRoot, resolveInvokedPath } from './util/workspace.js';
+import { errorCard, setPlain } from './util/ui.js';
+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';
@@ -26,6 +31,25 @@ if (major < 18) {
     console.error(kleur.red(`magicpixel requires Node.js >= 18 (you have ${process.versions.node}).`));
     process.exit(1);
 }
+// A monorepo has one setup at its root. Run from any game folder inside it,
+// every command uses that setup, so a second one is never created.
+{
+    const wsRoot = findWorkspaceRoot(process.cwd());
+    if (wsRoot) {
+        process.stderr.write(kleur.dim(`Using the MagicPixel setup in ${wsRoot}\n`));
+        // Paths typed by the user stay relative to where they ran the command.
+        process.env.MAGICPIXEL_INVOKED_FROM = process.cwd();
+        process.chdir(wsRoot);
+    }
+}
+// `--plain` anywhere: no colors, emoji or redraws (also NO_COLOR, CI, pipes).
+{
+    const i = process.argv.indexOf('--plain');
+    if (i > 1) {
+        process.argv.splice(i, 1);
+        setPlain(true);
+    }
+}
 const program = new Command();
 program
     .name('magicpixel')
@@ -39,7 +63,7 @@ const wrap = (commandName, fn) => async (...args) => {
         const err = e;
         const msg = err.message ?? String(e);
         // Multi-line messages are already formatted with "Fix:" hints — print as-is.
-        console.error(kleur.red(msg));
+        console.error(errorCard(msg));
         // Fire-and-forget telemetry → exit 1. `reportAndExit` decides whether
         // the error is worth surfacing on /admin/errors (5xx ApiErrors +
         // unexpected throws); user-fixable errors are filtered out inside
@@ -102,7 +126,8 @@ program
         throw new Error(`sync doesn't take a folder (got "${extra.join(' ')}").\n` +
             `  Fix: ${cmd(`sync --only ${extra[0].replace(/^\/+/, '')}`)}`);
     }
-    return syncCommand(opts);
+    const o = opts;
+    return syncCommand(o.only ? { ...o, only: o.only.map((f) => resolveInvokedPath(f)) } : o);
 }));
 program
     .command('push')
@@ -119,12 +144,12 @@ program
     .option('-y, --yes', 'Skip the confirmation question')
     .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(folder, opts)));
+    .action(wrap("resync", async (folder, opts) => resyncCommand(resolveInvokedPath(folder), opts)));
 program
     .command('connect <glob>')
     .description('Limit which game folders sync (default is all sprites)')
     .addHelpText('after', '\nExamples:\n  $ magicpixel connect \'assets/Sprites/Hero/**\'\n  $ magicpixel connect Runtime/UI/hud.png\n')
-    .action(wrap("connect", async (glob) => connectCommand(glob)));
+    .action(wrap("connect", async (glob) => connectCommand(resolveInvokedPath(glob))));
 program
     .command('search <query>')
     .description('Search indexed game PNGs (no network)')
@@ -151,4 +176,21 @@ program
     .command('whoami')
     .description('Verify the API key and show what it can see')
     .action(wrap("whoami", async () => whoamiCommand()));
+program
+    .command('why <path>')
+    .description('Explain what the next sync does with the game PNGs under a path')
+    .addHelpText('after', '\nExamples:\n  $ magicpixel why .SpineRaw/rabbit\n  $ magicpixel why Assets/Sprites/hero.png\n')
+    .action(wrap("why", async (path) => whyCommand(path)));
+program
+    .command('consolidate')
+    .description('Merge the MagicPixel setups of several game folders into one at this (monorepo) folder')
+    .option('-y, --yes', 'Skip the confirmation question')
+    .option('--dry-run', 'Show what would change without changing anything')
+    .action(wrap("consolidate", async (opts) => { await consolidateCommand(opts); }));
+program
+    .command('clean-strays')
+    .description('Delete copies sync wrote into outDir for sprites that belong to another game folder')
+    .option('-y, --yes', 'Skip the confirmation question')
+    .option('--dry-run', 'List the copies without deleting anything')
+    .action(wrap("clean-strays", async (opts) => cleanStraysCommand(opts)));
 program.parseAsync(process.argv);

package/dist/util/framework.js

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { relative, resolve } from 'node:path';
 const ENGINE_KINDS = new Set(['Unity', 'Godot', 'GameMaker']);
@@ -71,7 +71,23 @@ function hasMetaSidecar(dir) {
         return false;
     }
 }
-function detectEngineKind(cwd) {
+/**
+ * Members of a monorepo workspace (`magicpixel.json` with `"workspace": true`),
+ * as root-relative folder names. Null when `cwd` is not a workspace root.
+ */
+export function readWorkspaceMembers(cwd) {
+    try {
+        const parsed = JSON.parse(readFileSync(resolve(cwd, 'magicpixel.json'), 'utf8'));
+        if (parsed?.workspace !== true || !Array.isArray(parsed.members))
+            return null;
+        const members = parsed.members.filter((m) => typeof m === 'string' && /^[^/\\.][^/\\]*$/.test(m) && m !== '..');
+        return members.length > 0 ? members : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function detectEngineKind(cwd) {
     if (existsSync(resolve(cwd, 'project.godot')))
         return 'Godot';
     const projectSettings = resolveChildDir(cwd, 'ProjectSettings');
@@ -102,6 +118,8 @@ function detectEngineKind(cwd) {
 }
 /** Infer project kind from package.json deps, then engine marker files. */
 export async function detectProjectKind(cwd = process.cwd()) {
+    if (readWorkspaceMembers(cwd))
+        return 'Unity';
     const js = await detectJsKind(cwd);
     if (js)
         return js;

package/dist/util/gameScan.js

@@ -6,7 +6,7 @@
 import { existsSync } from 'node:fs';
 import { opendir, readdir } from 'node:fs/promises';
 import { relative, resolve } from 'node:path';
-import { isEngineKind, resolveChildDir } from './framework.js';
+import { detectEngineKind, isEngineKind, readWorkspaceMembers, resolveChildDir } from './framework.js';
 import { assertPathInsideRoot, sanitizeSourceRel } from './security.js';
 import { gameImportAdoptPath } from './pushPlan.js';
 import { matchGlob } from './globMatch.js';
@@ -73,6 +73,13 @@ function shouldSkipDir(name) {
         return true;
     return false;
 }
+/** Does a connect/exclude glob select this file? (cwd-, asset-root-, member- or key-relative) */
+export function entryMatchesGlob(e, g) {
+    return (matchGlob(e.sourceRel, g) ||
+        matchGlob(e.adoptRel, g) ||
+        matchGlob(e.key, g) ||
+        (!!e.member && matchGlob(`${e.member}/${e.adoptRel}`, g)));
+}
 function importRel(abs, cwd, assetRoot) {
     if (assetRoot) {
         const rootNorm = assetRoot.replace(/\\/g, '/').toLowerCase();
@@ -173,12 +180,49 @@ export async function indexGamePngs(kind, cwd = process.cwd(), outDir = '', opts
     if (!existsSync(scanRoot))
         return empty;
     const destNorm = outDir ? resolve(cwd, outDir).replace(/\\/g, '/').toLowerCase() : '';
+    const stats = { folders: 0, pngs: 0 };
+    const io = createLimit(SCAN_WALK_CONCURRENCY);
+    const report = bindScanProgress(opts.onProgress);
+    const members = readWorkspaceMembers(scanRoot);
+    if (members) {
+        // Each game folder is indexed exactly as if sync ran inside it (same keys),
+        // then its paths are re-rooted at the workspace.
+        const byKey = new Map();
+        const keyClashes = [];
+        for (const member of members) {
+            const dir = resolve(scanRoot, member);
+            if (!existsSync(dir))
+                continue;
+            const memberKind = detectEngineKind(dir) ?? kind;
+            for (const e of await indexOne(memberKind, dir, destNorm, io, report, stats)) {
+                const sourceRel = sanitizeSourceRel(`${member}/${e.sourceRel}`);
+                if (!sourceRel)
+                    continue;
+                if (byKey.has(e.key)) {
+                    keyClashes.push(sourceRel);
+                    continue;
+                }
+                byKey.set(e.key, { ...e, sourceRel, member });
+            }
+        }
+        report.flush?.();
+        opts.onProgress?.({ pngs: stats.pngs, folders: stats.folders });
+        const files = [...byKey.values()].sort((a, b) => a.sourceRel.localeCompare(b.sourceRel));
+        return keyClashes.length ? { files, keyClashes } : { files };
+    }
+    const files = await indexOne(kind, scanRoot, destNorm, io, report, stats);
+    report.flush?.();
+    opts.onProgress?.({ pngs: stats.pngs, folders: stats.folders });
+    return { files };
+}
+/** Index one game folder (project or package). Paths are relative to `cwd`. */
+async function indexOne(kind, cwd, destNorm, io, baseReport, stats) {
+    const scanRoot = resolve(cwd);
     const namedRoot = gameScanRoot(kind);
     const assetRoot = namedRoot ? resolveChildDir(cwd, namedRoot) : null;
     const found = [];
-    const stats = { folders: 0 };
-    const io = createLimit(SCAN_WALK_CONCURRENCY);
-    const report = bindScanProgress(opts.onProgress);
+    const offset = stats.pngs;
+    const report = (pngs, folders, current) => baseReport(offset + pngs, folders, current);
     // Full Unity games: walk Assets/ only. Listing the project root waits on
     // Library/Packages/cloud placeholders and looks hung at "1 folder".
     const startAt = isUnityGameProject(cwd, assetRoot) ? assetRoot : scanRoot;
@@ -191,8 +235,7 @@ export async function indexGamePngs(kind, cwd = process.cwd(), outDir = '', opts
             await walkPngs(dir, scanRoot, destNorm, found, Infinity, io, report, stats, null);
         }
     }
-    report.flush?.();
-    opts.onProgress?.({ pngs: found.length, folders: stats.folders });
+    stats.pngs += found.length;
     found.sort((a, b) => a.localeCompare(b));
     const files = [];
     for (const abs of found) {
@@ -200,7 +243,7 @@ export async function indexGamePngs(kind, cwd = process.cwd(), outDir = '', opts
         if (entry)
             files.push(entry);
     }
-    return { files };
+    return files;
 }
 /** One-line summary of exclude-dropped files, or null when none. */
 export function describeExcluded(r) {
@@ -225,7 +268,7 @@ export async function rootSpriteDotDirs(root) {
 export function matchConnectGlobs(index, globs, exclude = []) {
     if (globs.length === 0)
         return { entries: [] };
-    const hit = (e, g) => matchGlob(e.sourceRel, g) || matchGlob(e.adoptRel, g) || matchGlob(e.key, g);
+    const hit = entryMatchesGlob;
     // `exclude` wins over `connect`: excluded game files are never uploaded.
     const matched = [];
     const byRule = new Map();

package/dist/util/prompt.js

@@ -0,0 +1,15 @@
+import { stdin, stdout } from 'node:process';
+import { createInterface } from 'node:readline/promises';
+/** Ask a y/N question. Non-interactive runs (CI) always answer no. */
+export 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();
+    }
+}

package/dist/util/strayGuard.js

@@ -0,0 +1,76 @@
+/**
+ * Game-owned sprites (manifest `game: true` — they live in a connected library
+ * folder) belong to a real file in some game folder. Sync may write one only
+ * to its game path here, or beside siblings this folder already owns (a new
+ * variant saved next to its family). Otherwise it is skipped instead of being
+ * dropped as a stray copy into outDir — this works on a machine that never
+ * synced the owning folder, unlike the project-root registry.
+ */
+/** Library folder a manifest key sits in (`a/b/<doc>/<artboard>` → `a/b`). */
+export function libraryFolderOf(key) {
+    const parts = key.split('/');
+    return parts.length > 2 ? parts.slice(0, -2).join('/') : '';
+}
+export function splitStrayDownloads(entries, localKeys) {
+    const local = new Set(localKeys);
+    const localFolders = new Set();
+    for (const k of local) {
+        const f = libraryFolderOf(k);
+        if (f)
+            localFolders.add(f);
+    }
+    const keep = [];
+    const foreign = [];
+    for (const e of entries) {
+        const homeless = e.game === true && !local.has(e.key) && !localFolders.has(libraryFolderOf(e.key));
+        (homeless ? foreign : keep).push(e);
+    }
+    return { keep, foreign };
+}
+export function straySkipMessage(count, ownerRoot, rerun) {
+    const where = ownerRoot ? ` (they live in ${ownerRoot})` : '';
+    return (`${count.toLocaleString('en-US')} sprite${count === 1 ? '' : 's'} belong to another game folder${where} — skipped, nothing written here.\n` +
+        `  Sync from that folder instead, or ${rerun} to download copies here anyway.`);
+}
+/**
+ * New game-folder art (e.g. a variant saved as a new file) goes next to its
+ * siblings in the game — same folder, same file-naming style — instead of
+ * into outDir. Adds `key → game path` to `sourceByKey`; returns how many.
+ */
+export function placeBesideSiblings(sourceByKey, entries, liveRels) {
+    const byFolder = new Map();
+    for (const [k, rel] of sourceByKey) {
+        const f = libraryFolderOf(k);
+        if (!f)
+            continue;
+        const list = byFolder.get(f) ?? [];
+        list.push(rel);
+        byFolder.set(f, list);
+    }
+    const taken = new Set([...liveRels].map((r) => r.toLowerCase()));
+    for (const rel of sourceByKey.values())
+        taken.add(rel.toLowerCase());
+    let placed = 0;
+    for (const e of entries) {
+        if (e.game !== true || e.withheld || sourceByKey.has(e.key))
+            continue;
+        const sibs = byFolder.get(libraryFolderOf(e.key));
+        if (!sibs?.length)
+            continue;
+        const sib = [...sibs].sort()[0];
+        const slash = sib.lastIndexOf('/');
+        const dir = slash >= 0 ? sib.slice(0, slash) : '';
+        const base = sib.slice(slash + 1).replace(/\.png$/i, '');
+        const slug = e.key.split('/').pop() ?? '';
+        if (!slug)
+            continue;
+        const name = base.includes('_') && !base.includes('-') ? slug.replace(/-/g, '_') : slug;
+        const rel = dir ? `${dir}/${name}.png` : `${name}.png`;
+        if (taken.has(rel.toLowerCase()))
+            continue;
+        taken.add(rel.toLowerCase());
+        sourceByKey.set(e.key, rel);
+        placed++;
+    }
+    return placed;
+}

package/dist/util/ui.js

@@ -0,0 +1,156 @@
+/**
+ * One look for every CLI message: icons, colors, cards, progress bars.
+ * Plain mode (pipes, CI, NO_COLOR, TERM=dumb, --plain) drops colors, emoji and
+ * box drawing so logs stay greppable.
+ */
+import kleur from 'kleur';
+import ora from 'ora';
+let forcedPlain = false;
+/** True when output should be plain ASCII without colors. */
+export function isPlain(stream = process.stdout) {
+    if (forcedPlain)
+        return true;
+    const env = process.env;
+    if (env.MAGICPIXEL_PLAIN === '1' || 'NO_COLOR' in env || env.TERM === 'dumb' || env.CI)
+        return true;
+    return !stream.isTTY;
+}
+/** In-place updates (spinners, `\r` status lines) only on a live, non-plain terminal. */
+export function canRedraw(stream = process.stdout) {
+    return !isPlain(stream);
+}
+/** Spinner that stays silent in plain mode (no animation, no redraws). */
+export function spinner(opts) {
+    const o = typeof opts === 'string' ? { text: opts } : opts;
+    return ora({ spinner: 'dots', ...o, isEnabled: canRedraw() && o.isEnabled !== false });
+}
+/** `--plain` flag: force plain output for this run. */
+export function setPlain(on) {
+    forcedPlain = on;
+    if (on)
+        kleur.enabled = false;
+}
+const EMOJI = {
+    ok: '✅', warn: '⚠️ ', fail: '❌', tip: '💡', work: '⏳', watch: '👀', down: '⬇️ ', up: '⬆️ ',
+    removed: '🗑 ', sparkle: '✨', ghost: '👻', time: '⏱ ', paused: '⏸ ',
+};
+const ASCII = {
+    ok: '[ok]', warn: '[!]', fail: '[x]', tip: '[>]', work: '[..]', watch: '[watch]', down: '[v]', up: '[^]',
+    removed: '[-]', sparkle: '[*]', ghost: '[dry]', time: '[t]', paused: '[||]',
+};
+export function icon(name) {
+    return isPlain() ? ASCII[name] : EMOJI[name];
+}
+/** One status line: icon + colored text. */
+export const ui = {
+    ok: (text) => `${icon('ok')} ${kleur.green(text)}`,
+    warn: (text) => `${icon('warn')} ${kleur.yellow(text)}`,
+    fail: (text) => `${icon('fail')} ${kleur.red(text)}`,
+    /** `💡 Fix: <command>` — the command is highlighted so it's easy to copy. */
+    fix: (command, indent = '   ') => `${indent}${icon('tip')} Fix: ${kleur.cyan().bold(command)}`,
+    /** Numbered section header, e.g. `1/4 · Checking your login`. */
+    step: (n, title, total) => `${kleur.magenta().bold(total ? `${n}/${total}` : `Step ${n}`)} ${kleur.dim('·')} ${kleur.bold(title)}`,
+    /** `💡 Fix: …` for a sentence that already contains its command in backticks. */
+    fixText: (text, indent = '   ') => `${indent}${icon('tip')} ${kleur.cyan('Fix:')} ${text.replace(/`([^`]+)`/g, (_, c) => kleur.cyan().bold(c))}`,
+    name: (s) => kleur.cyan(s),
+    count: (n) => kleur.bold(n.toLocaleString('en-US')),
+    dryRun: () => `${icon('ghost')} ${kleur.magenta('Preview only — nothing changed.')}`,
+};
+// Strip ANSI so widths count visible characters.
+// eslint-disable-next-line no-control-regex
+const ANSI = /\x1b\[[0-9;]*m/g;
+export function visibleWidth(s) {
+    // Emoji are double width in most terminals; variation selectors take none.
+    let w = 0;
+    for (const ch of s.replace(ANSI, '')) {
+        const cp = ch.codePointAt(0);
+        if (cp === 0xfe0f || cp === 0x200d)
+            continue;
+        w += cp >= 0x1f000 || (cp >= 0x2600 && cp <= 0x27bf) || (cp >= 0x2b00 && cp <= 0x2bff) || cp === 0x23f1 || cp === 0x23f8 || cp === 0x23f3 ? 2 : 1;
+    }
+    return w;
+}
+/** Cut a plain line to `max` visible columns. */
+export function fitLine(line, columns) {
+    const max = Math.max(20, (columns ?? 80) - 1);
+    if (visibleWidth(line) <= max)
+        return line;
+    const plain = line.replace(ANSI, '');
+    let out = '';
+    for (const ch of plain) {
+        if (visibleWidth(out + ch) > max - 1)
+            break;
+        out += ch;
+    }
+    return `${out}…`;
+}
+/** Boxed summary. Plain mode prints a title line plus indented rows. */
+/** Break a line into pieces no wider than `max` visible columns (at spaces when possible). */
+export function wrapLine(line, max) {
+    if (visibleWidth(line) <= max)
+        return [line];
+    const plain = line.replace(ANSI, '');
+    const out = [];
+    let cur = '';
+    for (const word of plain.split(/(\s+)/)) {
+        if (visibleWidth(cur + word) <= max) {
+            cur += word;
+            continue;
+        }
+        if (cur.trim())
+            out.push(cur.trimEnd());
+        cur = word.trimStart();
+        while (visibleWidth(cur) > max) {
+            out.push(cur.slice(0, max));
+            cur = cur.slice(max);
+        }
+    }
+    if (cur.trim())
+        out.push(cur);
+    return out;
+}
+export function card(title, rows, tone = 'info', columns = process.stdout.columns, overflow = 'cut') {
+    const paint = tone === 'ok' ? kleur.green : tone === 'warn' ? kleur.yellow : tone === 'fail' ? kleur.red : kleur.cyan;
+    if (isPlain())
+        return [title, ...rows.map((r) => `  ${r}`)].join('\n');
+    const limit = Math.max(30, Math.min(72, (columns ?? 80) - 2));
+    const body = rows.flatMap((r) => (visibleWidth(r) <= limit - 6 ? [r] : overflow === 'wrap' ? wrapLine(r, limit - 6) : [fitLine(r, limit - 5)]));
+    const inner = Math.min(limit - 2, Math.max(visibleWidth(title) + 4, ...body.map((r) => visibleWidth(r) + 4)));
+    const top = `╭─ ${title} ${'─'.repeat(Math.max(0, inner - visibleWidth(title) - 3))}╮`;
+    const mid = body.map((r) => `│  ${r}${' '.repeat(Math.max(0, inner - visibleWidth(r) - 2))}│`);
+    const bottom = `╰${'─'.repeat(inner)}╯`;
+    return [paint(top), ...mid.map((m) => paint('│') + m.slice(1, -1) + paint('│')), paint(bottom)].join('\n');
+}
+/** `[████░░░░] 1,204 / 3,114 · 39%` */
+export function progressBar(done, total, width = 20) {
+    const pct = total === 0 ? 100 : Math.min(100, Math.round((done / total) * 100));
+    const filled = Math.round((pct / 100) * width);
+    const [on, off] = isPlain() ? ['#', '.'] : ['█', '░'];
+    return `[${kleur.green(on.repeat(filled))}${kleur.dim(off.repeat(width - filled))}] ${done.toLocaleString('en-US')}/${total.toLocaleString('en-US')} · ${pct}%`;
+}
+/** Format a multi-line error (first line = what happened, `Fix:` lines = how to fix). */
+export function errorCard(message) {
+    const lines = message.split('\n').map((l) => l.trimEnd()).filter((l, i) => i === 0 || l.trim().length > 0);
+    const [head, ...rest] = lines;
+    const rows = rest.map((l) => {
+        const t = l.trim();
+        if (/^fix:/i.test(t))
+            return `${icon('tip')} ${kleur.cyan(t)}`;
+        if (/request id/i.test(t))
+            return kleur.dim(t);
+        return t;
+    });
+    if (isPlain(process.stderr))
+        return [`${icon('fail')} ${head}`, ...rows.map((r) => `  ${r}`)].join('\n');
+    const cols = process.stderr.columns ?? process.stdout.columns ?? 80;
+    const text = head ?? 'Something went wrong';
+    const fits = visibleWidth(text) <= Math.min(72, cols - 2) - 8;
+    const title = `${icon('fail')} ${fits ? kleur.bold(text) : 'Something went wrong'}`;
+    return card(title, fits ? (rows.length ? rows : [kleur.dim('Run the command again, or add --plain for a log-friendly copy.')]) : [kleur.bold(text), ...rows], 'fail', cols, 'wrap');
+}
+export function formatDuration(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    const s = Math.round(ms / 1000);
+    return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m ${s % 60}s`;
+}

package/dist/util/workspace.js

@@ -0,0 +1,82 @@
+/**
+ * Monorepo workspaces: one `magicpixel.json` at the root syncs several game
+ * folders (Unity projects / packages). Each folder keeps the sprite names it
+ * would have on its own, so moving to a workspace never re-uploads anything.
+ */
+import { existsSync, readdirSync, realpathSync } from 'node:fs';
+import { basename, dirname, isAbsolute, relative, resolve } from 'node:path';
+import { detectEngineKind, isEngineKind, readWorkspaceMembers } from './framework.js';
+const NOT_MEMBERS = new Set(['node_modules', 'library', 'temp', 'build', 'builds', 'logs', 'obj']);
+/** Child folders of `root` that are game folders on their own. Sorted. */
+export function detectWorkspaceMembers(root) {
+    try {
+        return readdirSync(root, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && !e.isSymbolicLink() && !e.name.startsWith('.') && !NOT_MEMBERS.has(e.name.toLowerCase()))
+            .filter((e) => isEngineKind(detectEngineKind(resolve(root, e.name))))
+            .map((e) => e.name)
+            .sort((a, b) => a.localeCompare(b));
+    }
+    catch {
+        return [];
+    }
+}
+/** Nearest ancestor (excluding `cwd`) that is a workspace root, or null. */
+export function findWorkspaceRoot(cwd) {
+    let dir = dirname(resolve(cwd));
+    for (let i = 0; i < 32; i++) {
+        if (existsSync(resolve(dir, 'magicpixel.json')) && readWorkspaceMembers(dir))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+    return null;
+}
+/** Re-anchor a game-folder glob at the workspace root. */
+export function anchorGlob(member, glob) {
+    const g = glob.trim().replace(/^\.\//, '');
+    return `${member}/${g}`;
+}
+/**
+ * A path typed by the user, made relative to the setup folder. Commands run
+ * inside a game folder of a monorepo work from the root, so `Runtime` typed in
+ * `kr-core` means `kr-core/Runtime`.
+ */
+/** Resolve symlinks on the existing prefix so `/var` and `/private/var` compare equal. */
+function canonical(p) {
+    const abs = resolve(p);
+    const missing = [];
+    let dir = abs;
+    while (!existsSync(dir)) {
+        const parent = dirname(dir);
+        if (parent === dir)
+            return abs;
+        missing.push(basename(dir));
+        dir = parent;
+    }
+    try {
+        const real = realpathSync(dir);
+        return missing.length === 0 ? real : resolve(real, ...missing.reverse());
+    }
+    catch {
+        return abs;
+    }
+}
+export function resolveInvokedPath(typed, cwd = process.cwd()) {
+    const from = process.env.MAGICPIXEL_INVOKED_FROM;
+    if (!from || isAbsolute(typed))
+        return typed;
+    return relative(canonical(cwd), canonical(resolve(from, typed))).replace(/\\/g, '/') || '.';
+}
+/**
+ * Library folders don't include the game-folder name, so drop a leading
+ * monorepo member (`kr-core/Runtime` → `Runtime`) before matching them.
+ */
+export function stripMemberSegment(segments, cwd = process.cwd()) {
+    const members = readWorkspaceMembers(cwd);
+    if (!members || segments.length < 2)
+        return segments;
+    const first = segments[0];
+    return members.some((m) => m.toLowerCase() === first) ? segments.slice(1) : segments;
+}

package/package.json

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