@magicpixelart/cli 0.1.1 → 0.3.0

package/dist/commands/start.js

@@ -0,0 +1,105 @@
+import kleur from 'kleur';
+import { existsSync } from 'node:fs';
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import { resolve } from 'node:path';
+import { configPath } from '../config.js';
+import { hasPackageJson } from '../util/framework.js';
+import { findKeyInDotenv, readCredentialsSync, writeCredentials } from '../util/credentials.js';
+import { initCommand } from './init.js';
+import { loginCommand } from './login.js';
+import { syncCommand } from './sync.js';
+/**
+ * One-command bootstrap for new users. Runs init → key prompt → first sync →
+ * prints copy-pasteable watch instructions. Designed so a non-technical user
+ * can paste `npx magicpixel start` and end up with sprites on disk and a watch
+ * script ready to run.
+ */
+export async function startCommand(opts = {}) {
+    console.log(kleur.bold('🪄  MagicPixel — first-run setup'));
+    console.log(kleur.dim('  This walks you through getting your sprites onto disk.'));
+    console.log();
+    // 1. Need a package.json — refuse to scaffold into a non-project directory.
+    if (!hasPackageJson()) {
+        console.log(kleur.yellow('  MagicPixel needs a JavaScript project (package.json) to sync into.\n' +
+            '  Run this inside your project folder — the one with package.json.'));
+        return;
+    }
+    // 2. Run init non-interactively unless config already exists.
+    const cfgPath = configPath();
+    if (existsSync(cfgPath) && !opts.force) {
+        console.log(kleur.dim(`  Found existing magicpixel.json — skipping init.`));
+    }
+    else {
+        await initCommand({ yes: true, force: opts.force });
+    }
+    // 3. Offer to migrate any key sitting in .env / .env.local.
+    await maybeMigrateDotenvKey();
+    // 4. Make sure we have a usable key. Env var or stored credentials are fine.
+    const haveEnv = !!process.env.MAGICPIXEL_API_KEY;
+    const stored = readCredentialsSync();
+    if (!haveEnv && !stored) {
+        console.log();
+        console.log(kleur.bold('Step: connect your account'));
+        await loginCommand();
+    }
+    else if (haveEnv) {
+        console.log(kleur.dim('  Using MAGICPIXEL_API_KEY from your environment.'));
+    }
+    else {
+        console.log(kleur.dim('  Using stored credentials from .magicpixel/credentials.'));
+    }
+    // 5. First sync.
+    console.log();
+    console.log(kleur.bold('Step: first sync'));
+    await syncCommand({ full: true });
+    // 6. Tell the user how to run the watch loop.
+    console.log();
+    console.log(kleur.bold('You\'re set up. ✨'));
+    console.log();
+    console.log(`  ${kleur.green('▶')} ${kleur.bold('npm run magicpixel:watch')}   ${kleur.dim('# keeps sprites fresh while you edit them in MagicPixel')}`);
+    console.log();
+    if (await hasDevScript()) {
+        console.log(kleur.dim('  Tip: run your dev server and the watcher together with'));
+        console.log(kleur.dim('       `npx concurrently "npm run dev" "npm run magicpixel:watch"`'));
+        console.log();
+    }
+}
+async function hasDevScript() {
+    try {
+        const path = resolve(process.cwd(), 'package.json');
+        if (!existsSync(path))
+            return false;
+        const { readFile } = await import('node:fs/promises');
+        const pkg = JSON.parse(await readFile(path, 'utf8'));
+        return typeof pkg.scripts?.dev === 'string';
+    }
+    catch {
+        return false;
+    }
+}
+async function maybeMigrateDotenvKey() {
+    if (process.env.MAGICPIXEL_API_KEY)
+        return;
+    if (readCredentialsSync())
+        return;
+    if (!stdin.isTTY)
+        return;
+    const found = await findKeyInDotenv();
+    if (!found)
+        return;
+    if (!/^mp_(live|test)_[a-f0-9]{64}$/.test(found.value))
+        return;
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+        const ans = (await rl.question(`${kleur.cyan('?')} Found MAGICPIXEL_API_KEY in ${found.file} — move it to .magicpixel/credentials so it stays out of your bundler? ${kleur.dim('(Y/n)')} `)).trim().toLowerCase();
+        if (ans === 'n' || ans === 'no')
+            return;
+        await writeCredentials(found.value);
+        console.log(kleur.green(`✓ migrated key from ${found.file} → .magicpixel/credentials`));
+        console.log(kleur.dim(`  You can now remove the MAGICPIXEL_API_KEY line from ${found.file}.`));
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/commands/sync.js

@@ -5,11 +5,12 @@ import { mkdir, writeFile, unlink, readdir, rm, rename } from 'node:fs/promises'
 import { existsSync } from 'node:fs';
 import { dirname, relative, resolve } from 'node:path';
 import { loadConfig, loadState, saveState } from '../config.js';
-import { fetchAllManifest, fetchAssetBytes } from '../api.js';
+import { fetchAllManifest, fetchAssetBytes, ApiError } from '../api.js';
 import { fileSha256 } from '../util/hash.js';
-import { assetDiskPath } from '../util/paths.js';
+import { assetDiskPath, assetDiskPathFromKey } from '../util/paths.js';
 import { createLimit } from '../util/limit.js';
-import { emitTypedIndex } from '../util/emitIndex.js';
+import { emitTypedIndex, ensureAgentsDoc, scanDiskAssets } from '../util/emitIndex.js';
+import { assertPathInsideRoot, tmpPathFor } from '../util/security.js';
 export async function syncCommand(opts) {
     if (opts.watch) {
         await watchLoop(opts);
@@ -19,66 +20,134 @@ export async function syncCommand(opts) {
 }
 async function watchLoop(opts) {
     const intervalSec = typeof opts.watch === 'string' ? Math.max(2, parseInt(opts.watch, 10) || 10) : 10;
-    console.log(kleur.dim(`[watch] polling every ${intervalSec}s. Ctrl+C to stop.`));
+    // Header — print once on start. Project/asset count is best-effort; if the
+    // first manifest fetch fails we still want the loop to come up and retry.
+    let headerCount = null;
+    try {
+        const state = await loadState();
+        headerCount = state.assets ? Object.keys(state.assets).length : null;
+    }
+    catch {
+        // ignore — header is cosmetic
+    }
+    console.log(kleur.bold('👀 MagicPixel watching for changes…'));
+    console.log(`   Edit at:  ${kleur.cyan('https://magicpixel.art')}`);
+    if (headerCount !== null)
+        console.log(kleur.dim(`   Sprites:  ${headerCount}`));
+    console.log(kleur.dim(`   Polling:  every ${intervalSec}s   ·   Stop: Ctrl+C`));
+    console.log();
     let stopping = false;
+    let inFlight = false;
+    let resolveIdle = null;
+    let backoffSec = intervalSec;
+    let pausedForAuth = false;
     const onSigint = () => {
         if (stopping)
             return;
         stopping = true;
-        // \x1b[2K\r clears any in-flight status line before the goodbye message.
         process.stdout.write('\x1b[2K\r');
-        console.log(kleur.dim('[watch] stopped.'));
-        process.exit(0);
+        if (inFlight) {
+            console.log(kleur.dim('[watch] finishing current sync… (Ctrl+C again to force quit)'));
+            process.once('SIGINT', () => process.exit(130));
+        }
+        else {
+            console.log(kleur.dim('[watch] stopped.'));
+            process.exit(0);
+        }
     };
     process.on('SIGINT', onSigint);
-    // Run once eagerly so first sync isn't delayed by the interval.
-    let inFlight = false;
     const tick = async () => {
         if (inFlight || stopping)
             return;
         inFlight = true;
         try {
-            const r = await runOnce({ ...opts, quiet: true, watch: false });
-            if (r.downloaded > 0 || r.pruned > 0) {
+            const r = await runOnce({ ...opts, watch: false }, { watchMode: true });
+            // Reset backoff + auth-pause flags on any successful tick.
+            backoffSec = intervalSec;
+            pausedForAuth = false;
+            const changedCount = r.added.length + r.modified.length + r.removed.length + r.renamed.length;
+            if (opts.quiet)
+                return;
+            if (changedCount > 0) {
                 process.stdout.write('\x1b[2K\r');
-                console.log(`${kleur.dim(timestamp())} ${kleur.green('✓')} ${r.downloaded} downloaded` +
-                    (r.pruned ? `, ${r.pruned} pruned` : '') +
-                    (r.failed ? kleur.yellow(`, ${r.failed} failed`) : ''));
+                const verb = r.removed.length && !r.added.length && !r.modified.length ? 'Removed' : 'Pulled';
+                console.log(`${kleur.dim(timestamp())} ${kleur.green('✓')} ${verb} ${changedCount} ` +
+                    `change${changedCount === 1 ? '' : 's'} from MagicPixel:`);
+                printChanges(r, /* indent */ '  ');
             }
             else {
                 process.stdout.write(`\r\x1b[2K${kleur.dim(`${timestamp()} no changes (${r.unchanged} unchanged)`)}`);
             }
         }
         catch (e) {
-            console.log(`\n${kleur.dim(timestamp())} ${kleur.red('!')} ${e.message.split('\n')[0]}`);
+            const err = e;
+            const apiErr = err instanceof ApiError ? err : null;
+            const firstLine = err.message.split('\n')[0];
+            process.stdout.write('\x1b[2K\r');
+            if (apiErr && (apiErr.status === 401 || apiErr.status === 403)) {
+                if (!pausedForAuth) {
+                    console.log(`${kleur.dim(timestamp())} ${kleur.red('✗')} Your key looks invalid or rotated.`);
+                    console.log(kleur.dim('   Fix: run `magicpixel login` (this watcher will keep retrying every 30s).'));
+                }
+                pausedForAuth = true;
+                backoffSec = 30;
+            }
+            else if (isNetworkError(err)) {
+                if (backoffSec < 30) {
+                    console.log(`${kleur.dim(timestamp())} ${kleur.yellow('!')} MagicPixel is offline or your internet is. ` +
+                        `Sprites you already have still work. Retrying in ${Math.min(backoffSec * 2, 60)}s.`);
+                }
+                backoffSec = Math.min(backoffSec * 2, 60);
+            }
+            else {
+                console.log(`${kleur.dim(timestamp())} ${kleur.red('!')} ${firstLine}`);
+                backoffSec = Math.min(backoffSec * 2, 60);
+            }
         }
         finally {
             inFlight = false;
+            resolveIdle?.();
+            resolveIdle = null;
         }
     };
     await tick();
     while (!stopping) {
-        await new Promise((r) => setTimeout(r, intervalSec * 1000));
+        await new Promise((r) => setTimeout(r, backoffSec * 1000));
+        if (stopping)
+            break;
         await tick();
     }
+    if (inFlight) {
+        await new Promise((r) => {
+            resolveIdle = r;
+        });
+    }
+    console.log(kleur.dim('[watch] stopped.'));
+    process.exit(0);
 }
-async function runOnce(opts) {
+function isNetworkError(err) {
+    // The api layer wraps fetch failures as `manifest: network error (...)`;
+    // bare ENOTFOUND/ETIMEDOUT/etc. also surface here from `fetchAssetBytes`.
+    const msg = err.message;
+    return (/network error/i.test(msg) ||
+        /ENOTFOUND|ETIMEDOUT|ECONNRESET|ECONNREFUSED|EAI_AGAIN/i.test(msg) ||
+        /fetch failed/i.test(msg));
+}
+async function runOnce(opts, runOpts = {}) {
     const config = await loadConfig();
     const state = await loadState();
     const startedAt = new Date().toISOString();
     const concurrency = Math.max(1, Math.min(opts.concurrency ?? 6, 16));
-    const quiet = !!opts.quiet;
-    // Warn loudly when a custom endpoint is configured — easy to forget a test
-    // override before committing magicpixel.json to a real repo / CI.
-    if (!quiet && config.endpoint) {
+    const verbose = !opts.quiet && !runOpts.watchMode;
+    const shouldPrune = opts.prune !== false; // commander: --no-prune sets false
+    if (verbose && config.endpoint) {
         console.log(kleur.yellow(`! using custom endpoint: ${config.endpoint}`));
     }
-    // Incremental: only fetch what changed since last successful sync.
-    // --full forces a from-scratch fetch.
     const since = opts.full ? undefined : state.lastSync;
-    const spinner = quiet
-        ? null
-        : ora(since ? `Fetching manifest since ${humanTime(since)}…` : 'Fetching manifest…').start();
+    const previousAssets = state.assets ?? {}; // id → key from prior sync
+    const spinner = verbose
+        ? ora(since ? `Fetching manifest since ${humanTime(since)}…` : 'Fetching manifest…').start()
+        : null;
     let manifest;
     try {
         manifest = await fetchAllManifest(config, since);
@@ -88,15 +157,23 @@ async function runOnce(opts) {
         spinner?.fail('Manifest fetch failed');
         throw e;
     }
-    // Diff
+    // Detect renames: same id, different key vs prior snapshot.
+    const renamed = [];
+    for (const entry of manifest) {
+        const prevKey = previousAssets[entry.id];
+        if (prevKey && prevKey !== entry.key) {
+            renamed.push({ id: entry.id, oldKey: prevKey, newKey: entry.key });
+        }
+    }
+    // Diff against disk
     const toDownload = [];
-    const skipped = [];
     let bytesSaved = 0;
+    let unchanged = 0;
     for (const entry of manifest) {
         const diskPath = assetDiskPath(config.outDir, entry);
         const localSha = await fileSha256(diskPath);
         if (entry.sha256 && localSha && entry.sha256 === localSha) {
-            skipped.push(entry);
+            unchanged++;
             if (entry.size_bytes)
                 bytesSaved += entry.size_bytes;
         }
@@ -105,51 +182,77 @@ async function runOnce(opts) {
         }
     }
     // Orphan detection only when we have the full picture.
+    // (Renames also produce a stale path on disk — collected separately below.)
     let orphans = [];
     if (!since) {
         const remoteDiskPaths = new Set(manifest.map((e) => assetDiskPath(config.outDir, e)));
         orphans = (await findLocalPngs(resolve(process.cwd(), config.outDir)))
             .filter((p) => !remoteDiskPaths.has(p));
     }
-    if (!quiet) {
+    // Stale paths from detected renames (always pruned, even in incremental mode —
+    // otherwise the old PNG silently lingers next to the renamed copy).
+    const renameStalePaths = renamed
+        .map((r) => assetDiskPathFromKey(config.outDir, r.oldKey))
+        .filter((p) => existsSync(p));
+    // De-duplicate vs the full-sync orphan list.
+    const orphanSet = new Set(orphans);
+    for (const p of renameStalePaths)
+        orphanSet.add(p);
+    orphans = [...orphanSet];
+    if (verbose) {
         console.log();
         console.log(kleur.bold('Plan:'));
         console.log(`  ${kleur.green('+')} download ${toDownload.length}`);
-        console.log(`  ${kleur.dim('=')} unchanged ${skipped.length}${bytesSaved ? kleur.dim(` (~${formatBytes(bytesSaved)} saved)`) : ''}`);
-        if (since) {
+        console.log(`  ${kleur.dim('=')} unchanged ${unchanged}${bytesSaved ? kleur.dim(` (~${formatBytes(bytesSaved)} saved)`) : ''}`);
+        if (renamed.length)
+            console.log(`  ${kleur.cyan('↪')} renamed ${renamed.length}`);
+        if (since && !renamed.length) {
             console.log(`  ${kleur.dim('orphan check skipped (incremental — use --full)')}`);
         }
         else if (orphans.length > 0) {
-            const verb = opts.prune ? kleur.red('delete') : kleur.yellow('keep (orphan)');
+            const verb = shouldPrune ? kleur.red('delete') : kleur.yellow('keep (orphan)');
             console.log(`  ${verb} ${orphans.length}`);
         }
         console.log();
     }
     if (opts.dryRun) {
-        if (!quiet) {
+        if (verbose) {
             console.log(kleur.dim('--dry-run: no files written.'));
+            if (renamed.length > 0)
+                printRenames(renamed, { withHints: false });
             if (orphans.length > 0)
                 printOrphans(orphans);
         }
-        return { downloaded: 0, unchanged: skipped.length, pruned: 0, failed: 0, bytesIn: 0, bytesSaved };
+        return {
+            added: [],
+            modified: [],
+            unchanged,
+            removed: [],
+            renamed,
+            failed: 0,
+            bytesIn: 0,
+            bytesSaved,
+        };
     }
-    // Download with progress bar
     const result = {
-        downloaded: 0,
-        unchanged: skipped.length,
-        pruned: 0,
+        added: [],
+        modified: [],
+        unchanged,
+        removed: [],
+        renamed,
         failed: 0,
         bytesIn: 0,
         bytesSaved,
     };
     let progress = null;
-    if (!quiet && toDownload.length > 0) {
+    if (verbose && toDownload.length > 0) {
         progress = ora({ text: progressText(0, toDownload.length, 0), spinner: 'dots' }).start();
     }
     const run = createLimit(concurrency);
     let done = 0;
     await Promise.all(toDownload.map((entry) => run(async () => {
         const diskPath = assetDiskPath(config.outDir, entry);
+        const existedBefore = existsSync(diskPath);
         try {
             const localSha = await fileSha256(diskPath);
             const bytes = await fetchAssetBytes(config, entry.key, localSha);
@@ -157,8 +260,6 @@ async function runOnce(opts) {
                 result.unchanged++;
             }
             else {
-                // Verify the payload matches what the manifest advertised. Guards
-                // against silently writing a corrupted body to disk.
                 if (entry.sha256) {
                     const actual = createHash('sha256').update(bytes).digest('hex');
                     if (actual !== entry.sha256) {
@@ -166,10 +267,14 @@ async function runOnce(opts) {
                     }
                 }
                 await mkdir(dirname(diskPath), { recursive: true });
-                const tmp = `${diskPath}.${process.pid}.tmp`;
+                const tmp = tmpPathFor(diskPath);
+                assertPathInsideRoot(tmp, resolve(process.cwd(), config.outDir), 'outDir');
                 await writeFile(tmp, bytes);
                 await rename(tmp, diskPath);
-                result.downloaded++;
+                if (existedBefore)
+                    result.modified.push(entry.key);
+                else
+                    result.added.push(entry.key);
                 result.bytesIn += bytes.byteLength;
             }
         }
@@ -185,57 +290,146 @@ async function runOnce(opts) {
                 progress.text = progressText(done, toDownload.length, result.bytesIn);
         }
     })));
+    const downloaded = result.added.length + result.modified.length;
     if (progress) {
         if (result.failed === 0)
-            progress.succeed(`Downloaded ${result.downloaded} (${formatBytes(result.bytesIn)})`);
+            progress.succeed(`Downloaded ${downloaded} (${formatBytes(result.bytesIn)})`);
         else
-            progress.warn(`Downloaded ${result.downloaded}, failed ${result.failed} (${formatBytes(result.bytesIn)})`);
+            progress.warn(`Downloaded ${downloaded}, failed ${result.failed} (${formatBytes(result.bytesIn)})`);
     }
-    // Prune
-    if (opts.prune && orphans.length > 0) {
+    // Prune (now default — pass --no-prune to opt out).
+    if (shouldPrune && orphans.length > 0) {
+        const outRoot = resolve(process.cwd(), config.outDir);
         for (const p of orphans) {
-            await unlink(p);
-            if (!quiet)
-                console.log(`  ${kleur.red('-')} ${relative(process.cwd(), p)}`);
+            assertPathInsideRoot(p, outRoot, 'outDir');
+            try {
+                await unlink(p);
+                const relPath = relative(outRoot, p).replace(/\\/g, '/');
+                const key = relPath.endsWith('.png') ? relPath.slice(0, -4) : relPath;
+                result.removed.push(key);
+                if (verbose)
+                    console.log(`  ${kleur.red('-')} ${relative(process.cwd(), p)}`);
+            }
+            catch (e) {
+                if (verbose)
+                    console.log(`  ${kleur.yellow('!')} failed to prune ${relative(process.cwd(), p)}: ${e.message}`);
+            }
         }
         await pruneEmptyDirs(resolve(process.cwd(), config.outDir));
-        result.pruned = orphans.length;
     }
-    else if (!quiet && orphans.length > 0) {
+    else if (verbose && orphans.length > 0) {
         printOrphans(orphans);
     }
-    // Emit typed index if enabled AND any file change happened (or first sync).
-    // In incremental mode `manifest` only contains changed entries, so we must
-    // re-fetch the full manifest (cheap — JSON only) to write a complete index.
-    if (config.emitIndex && (result.downloaded > 0 || result.pruned > 0 || !since)) {
-        try {
-            const fullManifest = since ? await fetchAllManifest(config) : manifest;
-            const indexPath = await emitTypedIndex(config.outDir, fullManifest);
-            if (!quiet)
-                console.log(kleur.dim(`  index → ${relative(process.cwd(), indexPath)}`));
-        }
-        catch (e) {
-            if (!quiet)
-                console.log(kleur.yellow(`  index emit failed: ${e.message}`));
+    // Always persist the id → key snapshot so rename detection survives even
+    // when `emitIndex` is toggled off-then-on. `lastSync` only advances on a
+    // clean run, so partial-failure syncs are retried from the prior cursor.
+    const nextAssets = { ...previousAssets };
+    // Drop renamed ids (they'll be re-added with the new key below).
+    for (const r of renamed)
+        delete nextAssets[r.id];
+    for (const e of manifest)
+        nextAssets[e.id] = e.key;
+    // Drop ids whose key was pruned (orphans we just removed from disk).
+    if (result.removed.length > 0) {
+        const removedKeys = new Set(result.removed);
+        for (const [id, key] of Object.entries(nextAssets)) {
+            if (removedKeys.has(key))
+                delete nextAssets[id];
         }
     }
+    const nextState = { ...state, assets: nextAssets };
     if (result.failed === 0) {
-        await saveState({ lastSync: startedAt });
+        nextState.lastSync = startedAt;
+        delete nextState.lastError;
+    }
+    else {
+        nextState.lastError = `${result.failed} download${result.failed === 1 ? '' : 's'} failed at ${startedAt}`;
+    }
+    // Emit typed index from the filesystem — never from the manifest. This
+    // guarantees the barrel can never disagree with what bundlers see on disk,
+    // and removes the silent-failure mode where a flaky manifest call left
+    // `index.ts` stale despite the PNGs being fresh.
+    if (config.emitIndex) {
+        const idByKey = {};
+        for (const [id, key] of Object.entries(nextAssets))
+            idByKey[key] = id;
+        const diskEntries = await scanDiskAssets(config.outDir);
+        for (const e of diskEntries) {
+            if (idByKey[e.key])
+                e.id = idByKey[e.key];
+        }
+        const indexPath = await emitTypedIndex(config.outDir, diskEntries);
+        if (verbose)
+            console.log(kleur.dim(`  index → ${relative(process.cwd(), indexPath)}`));
+        // Nudge AI tools toward the typed index. Idempotent — `ensureAgentsDoc`
+        // no-ops once our marker section is present.
+        try {
+            const agentsResult = await ensureAgentsDoc(config.outDir);
+            if (verbose && agentsResult !== 'unchanged') {
+                console.log(kleur.dim(`  AGENTS.md ${agentsResult}`));
+            }
+        }
+        catch {
+            // Never let an AGENTS.md write failure break sync.
+        }
     }
-    else if (!quiet) {
+    await saveState(nextState);
+    if (result.failed > 0 && verbose) {
         console.log(kleur.yellow(`\n${result.failed} download${result.failed === 1 ? '' : 's'} failed — lastSync not advanced. Re-run to retry.`));
     }
-    if (!quiet) {
+    if (verbose) {
         console.log();
-        const summary = `downloaded ${result.downloaded}, unchanged ${result.unchanged}` +
-            (opts.prune ? `, pruned ${result.pruned}` : '') +
+        const summary = `downloaded ${downloaded} (added ${result.added.length}, modified ${result.modified.length}), ` +
+            `unchanged ${result.unchanged}` +
+            (result.bytesSaved ? kleur.dim(` (~${formatBytes(result.bytesSaved)} saved)`) : '') +
+            (shouldPrune ? `, pruned ${result.removed.length}` : '') +
+            (renamed.length ? `, renamed ${renamed.length}` : '') +
             (result.failed ? `, failed ${result.failed}` : '');
         console.log(result.failed ? kleur.yellow(`done with errors. ${summary}`) : kleur.green(`✓ done. ${summary}`));
+        printChanges(result, '  ');
+        if (renamed.length > 0)
+            printRenames(renamed, { withHints: true });
     }
     if (result.failed)
         process.exitCode = 1;
     return result;
 }
+const CHANGE_PRINT_CAP = 50;
+function printChanges(r, indent) {
+    const lines = [];
+    for (const k of r.added)
+        lines.push(`${indent}${kleur.green('+')} ${k}`);
+    for (const k of r.modified)
+        lines.push(`${indent}${kleur.cyan('~')} ${k}`);
+    for (const r2 of r.renamed)
+        lines.push(`${indent}${kleur.cyan('↪')} ${r2.oldKey} → ${r2.newKey}`);
+    for (const k of r.removed)
+        lines.push(`${indent}${kleur.red('-')} ${k}`);
+    if (lines.length === 0)
+        return;
+    if (lines.length <= CHANGE_PRINT_CAP) {
+        for (const l of lines)
+            console.log(l);
+    }
+    else {
+        for (const l of lines.slice(0, CHANGE_PRINT_CAP))
+            console.log(l);
+        console.log(`${indent}${kleur.dim(`…and ${lines.length - CHANGE_PRINT_CAP} more`)}`);
+    }
+}
+function printRenames(renamed, opts) {
+    if (renamed.length === 0)
+        return;
+    console.log();
+    console.log(opts.withHints ? kleur.bold('Renamed assets — update imports:') : kleur.cyan('Renames detected:'));
+    for (const r of renamed) {
+        console.log(`  ${kleur.cyan('↪')} ${r.oldKey} → ${r.newKey}`);
+        if (opts.withHints) {
+            console.log(`    ${kleur.dim(`MagicPixelAssets['${r.oldKey}']  →  MagicPixelAssets['${r.newKey}']`)}`);
+            console.log(`    ${kleur.dim(`or pin to id:  MagicPixelAssetsById['${r.id}']  (survives future renames)`)}`);
+        }
+    }
+}
 function progressText(done, total, bytes) {
     const pct = total === 0 ? 100 : Math.round((done / total) * 100);
     const barWidth = 24;
@@ -256,8 +450,7 @@ function timestamp() {
 }
 function humanTime(iso) {
     try {
-        const d = new Date(iso);
-        return d.toLocaleString();
+        return new Date(iso).toLocaleString();
     }
     catch {
         return iso;
@@ -269,17 +462,28 @@ function printOrphans(orphans) {
     for (const p of orphans) {
         console.log(`  ${kleur.dim('?')} ${relative(process.cwd(), p)}`);
     }
-    console.log(kleur.dim('  Run with --prune to delete them.'));
+    console.log(kleur.dim('  Pruning is on by default. Re-run without --no-prune to delete them.'));
 }
 async function findLocalPngs(dir) {
     if (!existsSync(dir))
         return [];
+    const root = resolve(dir);
     const out = [];
     async function walk(d) {
         const entries = await readdir(d, { withFileTypes: true });
         for (const ent of entries) {
+            if (ent.isSymbolicLink())
+                continue;
             const full = resolve(d, ent.name);
+            try {
+                assertPathInsideRoot(full, root, 'outDir');
+            }
+            catch {
+                continue;
+            }
             if (ent.isDirectory()) {
+                if (ent.name.startsWith('.'))
+                    continue;
                 await walk(full);
             }
             else if (ent.isFile() && ent.name.toLowerCase().endsWith('.png')) {
@@ -287,7 +491,7 @@ async function findLocalPngs(dir) {
             }
         }
     }
-    await walk(dir);
+    await walk(root);
     return out;
 }
 async function pruneEmptyDirs(root) {