@magicpixelart/cli 0.5.38 → 0.6.2

package/dist/index.js

@@ -17,20 +17,46 @@ 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';
+import { formatHelpTips } from './util/commandTips.js';
 // Node version guard
 const major = Number(process.versions.node.split('.')[0]);
 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')
     .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);
@@ -39,7 +65,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 +128,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 +146,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 +178,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/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/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,175 @@
+/**
+ * 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. */
+/**
+ * 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)
+        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`;
+}