@magicpixelart/cli 0.5.36 → 0.6.1

package/dist/config.js

@@ -113,6 +113,9 @@ export async function loadConfig(cwd = process.cwd()) {
         push: parsed.push === false ? false : undefined,
         connect,
         ...(parsed.syncOnly !== undefined ? { syncOnly: normalizeGlobList(parsed.syncOnly, 'syncOnly') } : {}),
+        ...(parsed.workspace === true && Array.isArray(parsed.members)
+            ? { workspace: true, members: normalizeGlobList(parsed.members, 'members') }
+            : {}),
     };
 }
 const MAX_GLOBS = 64;

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
@@ -94,6 +118,7 @@ program
     .option('-q, --quiet', 'Minimal output (for CI)')
     .option('-c, --concurrency <n>', 'Parallel downloads (1–16, default 6)', parseConcurrency)
     .option('--only <folder...>', 'Only sync these game folders (repeatable), e.g. Runtime/Sprites/Entities/decorations')
+    .option('--here', 'Download here even if these sprites are connected to another game folder')
     .argument('[extra...]')
     .addHelpText('after', '\nExamples:\n  $ magicpixel sync --watch --only Runtime/Sprites/Enemies   # one folder\n  $ magicpixel sync                # incremental sync\n  $ magicpixel sync --full         # ignore lastSync, re-check everything\n  $ magicpixel sync -w             # watch mode (2s; adaptive idle backoff; exit 2 after 5 auth failures)\n')
     .action(wrap("sync", async (extra, opts) => {
@@ -101,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')
@@ -118,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)')
@@ -150,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

@@ -4,9 +4,9 @@
  * globs select a working set; sync writes back to those original paths.
  */
 import { existsSync } from 'node:fs';
-import { opendir } from 'node:fs/promises';
+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,19 +180,62 @@ 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;
     const preferFirst = startAt === scanRoot ? assetRoot : null;
     await walkPngs(startAt, scanRoot, destNorm, found, Infinity, io, report, stats, preferFirst);
-    report.flush?.();
-    opts.onProgress?.({ pngs: found.length, folders: stats.folders });
+    // Full Unity games also keep sprite sources in root dot-folders next to
+    // Assets/ (e.g. `.SpineRaw`). Walk those too; Unity's own folders stay out.
+    if (startAt !== scanRoot) {
+        for (const dir of await rootSpriteDotDirs(scanRoot)) {
+            await walkPngs(dir, scanRoot, destNorm, found, Infinity, io, report, stats, null);
+        }
+    }
+    stats.pngs += found.length;
     found.sort((a, b) => a.localeCompare(b));
     const files = [];
     for (const abs of found) {
@@ -193,17 +243,50 @@ 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) {
+    if (!r.excluded)
+        return null;
+    return `${r.excluded.toLocaleString('en-US')} PNG${r.excluded === 1 ? '' : 's'} skipped by exclude rules (${r.topExclude}) — edit "exclude" in magicpixel.json to include them`;
+}
+/** Root-level dot-folders that may hold sprites (not VCS/editor/tool dirs). */
+export async function rootSpriteDotDirs(root) {
+    try {
+        const ents = await readdir(root, { withFileTypes: true });
+        return ents
+            .filter((e) => e.isDirectory() && !e.isSymbolicLink() && e.name.startsWith('.') && !shouldSkipDir(e.name))
+            .map((e) => resolve(root, e.name))
+            .sort();
+    }
+    catch {
+        return [];
+    }
 }
 /** Filter the index by connect globs minus exclude globs (cwd-, asset-root-relative or manifest key). */
 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 = index.files.filter((e) => globs.some((g) => hit(e, g)) && !exclude.some((g) => hit(e, g)));
+    const matched = [];
+    const byRule = new Map();
+    let excluded = 0;
+    for (const e of index.files) {
+        if (!globs.some((g) => hit(e, g)))
+            continue;
+        const rule = exclude.find((g) => hit(e, g));
+        if (rule === undefined)
+            matched.push(e);
+        else {
+            excluded++;
+            byRule.set(rule, (byRule.get(rule) ?? 0) + 1);
+        }
+    }
     matched.sort((a, b) => a.sourceRel.localeCompare(b.sourceRel));
-    return { entries: matched };
+    const topExclude = [...byRule.entries()].sort((a, b) => b[1] - a[1])[0]?.[0];
+    return { entries: matched, ...(excluded ? { excluded, topExclude } : {}) };
 }
 export function searchGameIndex(index, query) {
     const q = query.trim().toLowerCase();

package/dist/util/projectRoots.js

@@ -0,0 +1,73 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { atomicWrite } from './atomicWrite.js';
+export function registryPath(home = homedir()) {
+    return resolve(home, '.magicpixel', 'project-roots.json');
+}
+async function readRegistry(home) {
+    try {
+        const parsed = JSON.parse(await readFile(registryPath(home), 'utf8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Remember `root` as a home for this project's connected sprites. Best-effort. */
+const recorded = new Set();
+export async function recordProjectRoot(projectId, root, home) {
+    const memo = `${home ?? ''}\0${projectId}\0${resolve(root)}`;
+    if (recorded.has(memo))
+        return; // watch mode: once per run
+    recorded.add(memo);
+    try {
+        const reg = await readRegistry(home);
+        const abs = resolve(root);
+        const list = reg[projectId] ?? [];
+        if (list.includes(abs))
+            return;
+        reg[projectId] = [...list, abs].slice(-20);
+        const path = registryPath(home);
+        await mkdir(dirname(path), { recursive: true });
+        await atomicWrite(path, JSON.stringify(reg, null, 2));
+    }
+    catch {
+        /* registry is advisory */
+    }
+}
+/** Keys another folder already syncs to a real game path. */
+function connectedKeysAt(root) {
+    try {
+        const state = JSON.parse(readFileSync(resolve(root, '.magicpixel', 'state.json'), 'utf8'));
+        return new Set(Object.entries(state.synced ?? {}).filter(([, v]) => !!v?.sourceRel).map(([k]) => k));
+    }
+    catch {
+        return new Set();
+    }
+}
+/**
+ * Of the keys this run would download WITHOUT a local game path, how many
+ * belong to another registered folder. Returns the folder owning the most, or
+ * null when the download is safe.
+ */
+export async function findForeignOwner(projectId, cwd, downloadKeysWithoutLocalPath, home) {
+    if (downloadKeysWithoutLocalPath.length === 0)
+        return null;
+    const here = resolve(cwd);
+    const roots = ((await readRegistry(home))[projectId] ?? []).filter((r) => r !== here && existsSync(r));
+    let best = null;
+    for (const root of roots) {
+        const owned = connectedKeysAt(root);
+        const count = downloadKeysWithoutLocalPath.filter((k) => owned.has(k)).length;
+        if (count > 0 && (!best || count > best.count))
+            best = { root, count };
+    }
+    return best;
+}
+export function foreignOwnerMessage(owner, cwd, rerun) {
+    return (`This folder isn't the game these sprites are connected to.\n` +
+        `  ${owner.count} sprite${owner.count === 1 ? '' : 's'} live in ${owner.root}, not ${resolve(cwd)}.\n` +
+        `  Fix: cd "${owner.root}" and run sync there — or ${rerun} to download copies here anyway.`);
+}

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

@@ -39,19 +39,3 @@ export function formatSlowTickLine(elapsedSec, lastStatus) {
         ? `${what} — still working (${elapsed})`
         : `Still working (${elapsed})`;
 }
-/**
- * Fit a carriage-return status line to one terminal row. `\r\x1b[2K` only
- * clears the row the cursor is on, so a line that wraps leaves its first rows
- * behind and the next status prints after them (long "Looking through your
- * game sprites… <folder>" lines piled up this way). No width (not a TTY) →
- * unchanged.
- */
-export function fitStatusLine(line, columns) {
-    if (!columns || columns < 2)
-        return line;
-    const max = columns - 1; // leave the last cell free so the cursor can't wrap
-    const chars = Array.from(line);
-    if (chars.length <= max)
-        return line;
-    return `${chars.slice(0, max - 1).join('')}…`;
-}