@magicpixelart/cli 0.5.8 → 0.5.10

package/dist/commands/sync.js

@@ -7,11 +7,13 @@ import { dirname, relative, resolve } from 'node:path';
 import { loadConfig, loadState, saveState } from '../config.js';
 import { fetchAllManifest, fetchAssetBytes, ApiError, getLastProjectInfo } from '../api.js';
 import { fileSha256 } from '../util/hash.js';
-import { assetDiskPath, assetDiskPathFromKey, pruneEmptyDirs, walkOutDirPngs } from '../util/paths.js';
+import { pruneEmptyDirs, walkOutDirPngs } from '../util/paths.js';
 import { createLimit } from '../util/limit.js';
 import { emitTypedIndex, ensureAgentsDoc, scanDiskAssets } from '../util/emitIndex.js';
-import { assertPathInsideRoot } from '../util/security.js';
-import { detectProjectKind } from '../util/framework.js';
+import { assertPathInsideRoot, assertSafeIoPath } from '../util/security.js';
+import { detectProjectKind, isEngineKind } from '../util/framework.js';
+import { indexGamePngs, matchConnectGlobs, GAME_INDEX_CAP_HINT, connectCapMessage } from '../util/gameScan.js';
+import { collectSourceRelMap, isPathInside, syncDiskPathFromKey } from '../util/syncPath.js';
 import { DEFAULT_UNITY_PPU, writeMissingUnityMetas } from '../util/unityMeta.js';
 import { filterUnityManifest } from '../util/unityFilter.js';
 import { selectFullSyncOrphans } from '../util/prunePolicy.js';
@@ -21,6 +23,7 @@ import { maxIsoTimestamp } from '../util/iso.js';
 import { formatBytes } from '../util/format.js';
 import { computePreviousKeyOrphans } from '../util/previousKeyOrphans.js';
 import { cmd } from '../util/invoke.js';
+import { formatWatchSpriteLine } from '../util/watchCopy.js';
 import { runPush } from './push.js';
 export async function syncCommand(opts) {
     // Sweep any leaked `<file>.<pid>.<hex>.tmp` files left behind by a prior
@@ -48,20 +51,33 @@ async function watchLoop(opts) {
     // Commander already validated the numeric value (2–3600); the `?? 2`
     // covers the bare boolean `-w` form.
     const intervalSec = typeof opts.watch === 'string' ? parseInt(opts.watch, 10) : 2;
-    // 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
-    }
+    // Header — print once on start. Counts are best-effort; if the first
+    // manifest fetch fails we still want the loop to come up and retry.
     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}`));
+    let countSpinner = null;
+    if (!opts.quiet) {
+        try {
+            const config = await loadConfig();
+            const kind = await detectProjectKind();
+            if (isEngineKind(kind) && (config.connect?.length ?? 0) > 0) {
+                countSpinner = ora({ text: 'Counting sprites in your game…', spinner: 'dots' }).start();
+            }
+        }
+        catch {
+            /* header is cosmetic */
+        }
+    }
+    const spriteLine = await loadWatchSpriteLine();
+    if (countSpinner) {
+        if (spriteLine)
+            countSpinner.succeed(spriteLine.trim());
+        else
+            countSpinner.stop();
+    }
+    else if (spriteLine && !opts.quiet) {
+        console.log(kleur.dim(spriteLine));
+    }
     console.log(kleur.dim(`   Polling:  every ${intervalSec}s (slows when idle)   ·   Stop: Ctrl+C`));
     console.log();
     let stopping = false;
@@ -104,12 +120,12 @@ async function watchLoop(opts) {
         wakeStop();
         process.stdout.write('\x1b[2K\r');
         if (inFlight) {
-            console.log(kleur.dim(`[watch] finishing current sync… (${signal} again to force quit)`));
+            console.log(kleur.dim(`Still finishing this check… (${signal} again to stop now)`));
             process.once(signal, () => process.exit(signal === 'SIGINT' ? 130 : 143));
         }
         else {
             if (!opts.quiet)
-                console.log(kleur.dim('[watch] stopped.'));
+                console.log(kleur.dim('Stopped watching.'));
             // Preserve any exit code already set by a prior failed tick.
             process.exit(process.exitCode ?? 0);
         }
@@ -120,8 +136,14 @@ async function watchLoop(opts) {
         if (inFlight || stopping)
             return;
         inFlight = true;
+        const onStatus = (msg) => {
+            if (opts.quiet)
+                return;
+            process.stdout.write(`\r\x1b[2K${kleur.dim(`${timestamp()} ${msg}`)}`);
+        };
         try {
-            const r = await runOnce({ ...opts, watch: false }, { watchMode: true });
+            onStatus('Checking MagicPixel…');
+            const r = await runOnce({ ...opts, watch: false }, { watchMode: true, onStatus });
             // Reset backoff on any successful tick. Resume message fires once when
             // we recover from an auth pause — `getApiKey()` re-reads
             // .magicpixel/credentials on every call, so a `magicpixel login` in
@@ -163,7 +185,7 @@ async function watchLoop(opts) {
                 printChanges(r, /* indent */ '  ');
             }
             else {
-                process.stdout.write(`\r\x1b[2K${kleur.dim(`${timestamp()} no changes (${r.unchanged} unchanged)`)}`);
+                process.stdout.write(`\r\x1b[2K${kleur.dim(`${timestamp()} Waiting for edits… (${r.unchanged} up to date)`)}`);
             }
         }
         catch (e) {
@@ -246,7 +268,7 @@ async function watchLoop(opts) {
         await tick();
     }
     if (!opts.quiet)
-        console.log(kleur.dim('[watch] stopped.'));
+        console.log(kleur.dim('Stopped watching.'));
     // Preserve any non-zero exit code set by a failed tick — don't mask a
     // download failure with a clean exit just because the user pressed Ctrl+C.
     process.exit(process.exitCode ?? 0);
@@ -307,12 +329,35 @@ export function classifyTickError(err, state) {
     }
     return { kind: 'other', nextBackoffSec: Math.min(state.backoffSec * 2, 60) };
 }
+async function loadWatchSpriteLine() {
+    try {
+        const config = await loadConfig();
+        const state = await loadState();
+        const lastPulled = state.assets ? Object.keys(state.assets).length : 0;
+        let workingSet = 0;
+        const kind = await detectProjectKind();
+        if (isEngineKind(kind) && (config.connect?.length ?? 0) > 0) {
+            const index = await indexGamePngs(kind, process.cwd(), config.outDir);
+            const matched = matchConnectGlobs(index, config.connect);
+            workingSet = matched.total;
+        }
+        else if (state.synced) {
+            workingSet = Object.keys(state.synced).length;
+        }
+        return formatWatchSpriteLine({ workingSet, lastPulled });
+    }
+    catch {
+        return null;
+    }
+}
 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 verbose = !opts.quiet && !runOpts.watchMode;
+    const live = !opts.quiet;
+    const onStatus = runOpts.onStatus;
     const shouldPrune = opts.prune !== false; // commander: --no-prune sets false
     if (verbose && config.endpoint) {
         console.log(kleur.yellow(`! using custom endpoint: ${config.endpoint}`));
@@ -322,6 +367,8 @@ async function runOnce(opts, runOpts = {}) {
     const spinner = verbose
         ? ora(since ? `Fetching manifest since ${humanTime(since)}…` : 'Fetching manifest…').start()
         : null;
+    if (!spinner)
+        onStatus?.(since ? 'Checking MagicPixel for edits…' : 'Fetching your sprites from MagicPixel…');
     let manifest;
     try {
         manifest = await fetchAllManifest(config, since);
@@ -341,15 +388,44 @@ async function runOnce(opts, runOpts = {}) {
     }
     catch (e) {
         spinner?.fail('Manifest fetch failed');
+        // One-shot sync / first-run: still import local sprites (ingest is a
+        // different host). Watch ticks skip this — otherwise a 546 would POST
+        // every PNG every poll.
+        if (!runOpts.watchMode) {
+            const pushed = await maybePushLocalSprites(config.push, verbose);
+            if (verbose && pushed && pushed.created > 0) {
+                console.log();
+                console.log(kleur.green(`✓ pushed ${pushed.created} working-set sprite${pushed.created === 1 ? '' : 's'} into MagicPixel anyway.`));
+                console.log(kleur.dim('  Refresh Connected in the library to see them, then re-run sync to pull.'));
+            }
+        }
         throw e;
     }
     // Unity projects sync only the artboards flagged "Sync to Unity" in the
     // editor (parity with the in-app sync button). `unitySyncAll: true` in
     // magicpixel.json opts back into everything.
+    onStatus?.('Looking through your game sprites…');
     const projectKind = await detectProjectKind();
+    const gameIndex = isEngineKind(projectKind)
+        ? await indexGamePngs(projectKind, process.cwd(), config.outDir)
+        : { files: [], capped: false };
+    const connected = matchConnectGlobs(gameIndex, config.connect ?? []);
+    const sourceByKey = collectSourceRelMap(connected.entries, state.synced);
+    if (verbose && gameIndex.capped) {
+        console.log(kleur.yellow(`! ${GAME_INDEX_CAP_HINT}`));
+    }
+    if (verbose && connected.capped) {
+        console.log(kleur.yellow(`! ${connectCapMessage(connected.total, connected.entries.length)}`));
+    }
+    if (verbose && isEngineKind(projectKind)) {
+        console.log(kleur.dim(`  game index → ${gameIndex.files.length} PNG${gameIndex.files.length === 1 ? '' : 's'} · working set ${connected.entries.length}` +
+            (connected.capped ? ` of ${connected.total} matched` : '')));
+    }
+    const pathForKey = (key) => syncDiskPathFromKey(config.outDir, key, sourceByKey);
     // Files whose artboard is no longer flagged for Unity. Deleted even in
     // incremental mode: un-checking the box in the editor must actually remove
     // the sprite from the game project, not leave a stale copy behind.
+    // Working-set (sourceRel) files are never deleted — they're the user's art.
     const deselectedPaths = [];
     // Sprites whose "Sync to Unity" flag the server omitted. Not downloaded
     // (strict opt-in) but explicitly shielded from pruning: a transient server
@@ -365,11 +441,13 @@ async function runOnce(opts, runOpts = {}) {
         for (const entry of manifest) {
             if (filtered.entries.includes(entry))
                 continue;
-            const p = assetDiskPath(config.outDir, entry);
+            const p = pathForKey(entry.key);
             if (unknownSet.has(entry)) {
                 unknownFlagPaths.add(p);
                 continue;
             }
+            if (sourceByKey.has(entry.key))
+                continue;
             if (existsSync(p))
                 deselectedPaths.push(p);
         }
@@ -379,7 +457,7 @@ async function runOnce(opts, runOpts = {}) {
             if (verbose) {
                 console.log();
                 console.log(kleur.yellow('! No artboards are flagged "Sync to Unity" — nothing to pull.'));
-                console.log(kleur.dim('  Existing game sprites will still be imported into MagicPixel.'));
+                console.log(kleur.dim(`  Working-set sprites (\`connect\` in magicpixel.json) still push into MagicPixel.`));
                 console.log(kleur.dim('  Flag folders/artboards in the library to pull them back into Unity.'));
             }
             const empty = {
@@ -392,7 +470,7 @@ async function runOnce(opts, runOpts = {}) {
                 bytesSaved: 0,
                 renamed: [],
             };
-            await maybePushLocalSprites(config.push, verbose);
+            await maybePushLocalSprites(config.push, verbose, gameIndex, live && !!runOpts.watchMode);
             return empty;
         }
         const skipped = manifest.length - filtered.entries.length;
@@ -409,13 +487,18 @@ async function runOnce(opts, runOpts = {}) {
             renamed.push({ id: entry.id, oldKey: prevKey, newKey: entry.key });
         }
     }
+    for (const r of renamed) {
+        const rel = sourceByKey.get(r.oldKey);
+        if (rel && !sourceByKey.has(r.newKey))
+            sourceByKey.set(r.newKey, rel);
+    }
     // Compute the disk path once per entry and reuse it across the diff /
     // orphan / download loops — saves three resolves + two security asserts
     // per asset on large projects. Every entry in `manifest` is pre-seeded, so
     // the lookup never misses; non-null assertion is safe.
     const diskPathById = new Map();
     for (const entry of manifest) {
-        diskPathById.set(entry.id, assetDiskPath(config.outDir, entry));
+        diskPathById.set(entry.id, pathForKey(entry.key));
     }
     const pathFor = (entry) => diskPathById.get(entry.id);
     // Diff against disk. SHA pre-check runs through the same concurrency pool
@@ -423,6 +506,9 @@ async function runOnce(opts, runOpts = {}) {
     // the dominant wall-clock cost of an incremental sync. We cache each result
     // so the download loop can reuse it for `If-None-Match` ETags instead of
     // re-hashing the same file moments later.
+    onStatus?.(manifest.length > 0
+        ? `Comparing ${manifest.length.toLocaleString('en-US')} sprite${manifest.length === 1 ? '' : 's'} with files on disk…`
+        : 'Checking MagicPixel…');
     const diffLimit = createLimit(concurrency);
     const shaByEntryId = new Map();
     const toDownload = [];
@@ -456,7 +542,7 @@ async function runOnce(opts, runOpts = {}) {
             .concat(Object.values(previousAssets))
             .map((key) => {
             try {
-                return assetDiskPathFromKey(config.outDir, key);
+                return pathForKey(key);
             }
             catch {
                 return '';
@@ -516,15 +602,24 @@ async function runOnce(opts, runOpts = {}) {
     }
     // Stale paths from detected renames (always pruned, even in incremental mode —
     // otherwise the old PNG silently lingers next to the renamed copy).
+    const outRoot = resolve(process.cwd(), config.outDir);
     const renameStalePaths = renamed
-        .map((r) => assetDiskPathFromKey(config.outDir, r.oldKey))
-        .filter((p) => existsSync(p));
+        .map((r) => {
+        try {
+            return pathForKey(r.oldKey);
+        }
+        catch {
+            return '';
+        }
+    })
+        .filter((p) => p && existsSync(p) && isPathInside(p, outRoot));
     // De-duplicate vs the full-sync orphan list.
     const orphanSet = new Set(orphans);
     for (const p of renameStalePaths)
         orphanSet.add(p);
     // Un-checked "Sync to Unity" artboards: their PNG (and .meta) leaves the
-    // Unity project on the next sync, incremental or not.
+    // Unity project on the next sync, incremental or not. Working-set originals
+    // are never in this list.
     for (const p of deselectedPaths)
         orphanSet.add(p);
     // Server-side rename history. Each manifest entry carries the composite
@@ -536,11 +631,13 @@ async function runOnce(opts, runOpts = {}) {
     const prevKeyResult = computePreviousKeyOrphans({
         manifest,
         remoteDiskPaths,
-        resolveDiskPath: (key) => assetDiskPathFromKey(config.outDir, key),
+        resolveDiskPath: (key) => pathForKey(key),
         fileExists: existsSync,
     });
-    for (const p of prevKeyResult.orphanPaths)
-        orphanSet.add(p);
+    for (const p of prevKeyResult.orphanPaths) {
+        if (isPathInside(p, outRoot))
+            orphanSet.add(p);
+    }
     for (const r of prevKeyResult.renames) {
         if (!renamed.some((x) => x.id === r.id && x.oldKey === r.oldKey)) {
             renamed.push(r);
@@ -631,7 +728,8 @@ async function runOnce(opts, runOpts = {}) {
         bytesSaved,
     };
     let progress = null;
-    if (verbose && toDownload.length > 0) {
+    if (live && toDownload.length > 0) {
+        onStatus?.(`Pulling ${toDownload.length.toLocaleString('en-US')} updated sprite${toDownload.length === 1 ? '' : 's'}…`);
         progress = ora({ text: progressText(0, toDownload.length, 0), spinner: 'dots' }).start();
     }
     const run = createLimit(concurrency);
@@ -679,6 +777,7 @@ async function runOnce(opts, runOpts = {}) {
                 // "fix" this back to atomicWrite without also changing the
                 // tmp-name pattern AND verifying HMR end-to-end in a consumer app.
                 try {
+                    await assertSafeIoPath(diskPath, process.cwd(), { forWrite: true });
                     await mkdir(dirname(diskPath), { recursive: true });
                     await writeFile(diskPath, bytes);
                 }
@@ -686,7 +785,9 @@ async function runOnce(opts, runOpts = {}) {
                     throw friendlyFsError(fsErr, {
                         operation: `Writing asset`,
                         path: diskPath,
-                        hint: `Sync can't continue until outDir (${config.outDir}) is writable.`,
+                        hint: sourceByKey.has(entry.key)
+                            ? 'Sync can\'t continue until the original game file is writable.'
+                            : `Sync can't continue until outDir (${config.outDir}) is writable.`,
                     });
                 }
                 if (existedBefore)
@@ -720,17 +821,24 @@ async function runOnce(opts, runOpts = {}) {
     })));
     const downloaded = result.added.length + result.modified.length;
     if (progress) {
-        if (result.failed === 0)
+        if (runOpts.watchMode) {
+            progress.stop();
+        }
+        else if (result.failed === 0) {
             progress.succeed(`Downloaded ${downloaded} (${formatBytes(result.bytesIn)})`);
-        else
+        }
+        else {
             progress.warn(`Downloaded ${downloaded}, failed ${result.failed} (${formatBytes(result.bytesIn)})`);
+        }
     }
     // Unity: write pixel-art-correct `.meta` sidecars so sprites import with
     // point filtering / no compression instead of Unity's blurry defaults —
     // parity with the in-app "Sync to Unity" button. Only missing sidecars are
     // written, so importer settings the user tweaked in Unity are preserved.
     if (projectKind === 'Unity') {
-        const meta = await writeMissingUnityMetas(manifest.map((entry) => ({ id: entry.id, pngPath: pathFor(entry) })), config.unityPpu ?? DEFAULT_UNITY_PPU);
+        const meta = await writeMissingUnityMetas(manifest
+            .filter((entry) => !sourceByKey.has(entry.key))
+            .map((entry) => ({ id: entry.id, pngPath: pathFor(entry) })), config.unityPpu ?? DEFAULT_UNITY_PPU);
         if (verbose && meta.written > 0) {
             console.log(kleur.dim(`  unity → ${meta.written} .meta file${meta.written === 1 ? '' : 's'} written`));
         }
@@ -740,15 +848,17 @@ async function runOnce(opts, runOpts = {}) {
     }
     // Prune (now default — pass --no-prune to opt out).
     if (shouldPrune && orphans.length > 0) {
-        const outRoot = resolve(process.cwd(), config.outDir);
+        const pruneRoot = resolve(process.cwd(), config.outDir);
         for (const p of orphans) {
-            assertPathInsideRoot(p, outRoot, 'outDir');
+            if (!isPathInside(p, pruneRoot))
+                continue;
+            assertPathInsideRoot(p, pruneRoot, 'outDir');
             try {
                 await unlink(p);
                 // Unity sidecar follows its PNG — a stranded .meta shows up in Unity
                 // as a missing-asset warning.
                 await unlink(`${p}.meta`).catch(() => { });
-                const relPath = relative(outRoot, p).replace(/\\/g, '/');
+                const relPath = relative(pruneRoot, p).replace(/\\/g, '/');
                 const key = relPath.endsWith('.png') ? relPath.slice(0, -4) : relPath;
                 result.removed.push(key);
                 if (verbose)
@@ -816,28 +926,37 @@ async function runOnce(opts, runOpts = {}) {
     // without re-fetching the manifest. Renamed/pruned keys are dropped so a
     // stale entry can never send an edit to the wrong artboard.
     const nextSynced = { ...(state.synced ?? {}) };
-    for (const r of renamed)
+    for (const r of renamed) {
         delete nextSynced[r.oldKey];
+    }
     for (const key of result.removed)
         delete nextSynced[key];
+    const writtenKeys = new Set([...result.added, ...result.modified]);
     for (const entry of manifest) {
         if (!entry.asset_id)
             continue;
         const sha = entry.sha256 ?? (await fileSha256(pathFor(entry)));
         if (!sha)
             continue;
+        const prev = nextSynced[entry.key];
+        const diskSha256 = writtenKeys.has(entry.key)
+            ? sha
+            : (shaByEntryId.get(entry.id) ?? prev?.diskSha256 ?? sha);
+        const sourceRel = sourceByKey.get(entry.key);
         // Legacy single-PNG rows have no artboard address (`layer_idx: -1`). Record
         // them anyway, flagged, so `push` skips them with a hint instead of
         // adopting the same art as a second document.
         if (typeof entry.layer_idx !== 'number' || entry.layer_idx < 0) {
-            nextSynced[entry.key] = { assetId: entry.asset_id, layerIdx: 0, sha256: sha, legacy: true };
+            nextSynced[entry.key] = { assetId: entry.asset_id, layerIdx: 0, sha256: sha, diskSha256, legacy: true, ...(sourceRel ? { sourceRel } : {}) };
             continue;
         }
         nextSynced[entry.key] = {
             assetId: entry.asset_id,
             layerIdx: entry.layer_idx,
             sha256: sha,
+            diskSha256,
             ...(typeof entry.layer_count === 'number' ? { layers: entry.layer_count } : {}),
+            ...(sourceRel ? { sourceRel } : {}),
         };
     }
     const nextState = { ...state, assets: nextAssets, synced: nextSynced };
@@ -918,23 +1037,25 @@ async function runOnce(opts, runOpts = {}) {
         if (renamed.length > 0)
             printRenames(renamed, { withHints: true });
     }
-    await maybePushLocalSprites(config.push, verbose);
+    onStatus?.('Checking your game files…');
+    await maybePushLocalSprites(config.push, verbose, gameIndex, live && !!runOpts.watchMode);
     if (result.failed)
         process.exitCode = 1;
     return result;
 }
-async function maybePushLocalSprites(pushEnabled, verbose) {
+async function maybePushLocalSprites(pushEnabled, verbose, gameIndex, announceErrors = verbose) {
     if (pushEnabled === false)
-        return;
+        return null;
     try {
-        await runPush({ quiet: !verbose });
+        return await runPush({ quiet: !verbose, gameIndex });
     }
     catch (e) {
-        if (verbose) {
+        if (announceErrors) {
             console.log();
-            console.log(kleur.yellow(`! could not import local sprites into MagicPixel: ${e.message}`));
+            console.log(kleur.yellow(`! could not update MagicPixel from your game files: ${e.message}`));
             console.log(kleur.dim(`  Fix: run \`${cmd('push')}\` once the connection is healthy.`));
         }
+        return null;
     }
 }
 const CHANGE_PRINT_CAP = 50;

package/dist/config.js

@@ -1,7 +1,7 @@
 import { readFile, mkdir, rename, writeFile, chmod } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
-import { assertSafeOutDir, MAX_GLOB_LEN, validateEndpointUrl } from './util/security.js';
+import { assertSafeOutDir, MAX_GLOB_LEN, sanitizeSourceRel, validateEndpointUrl } from './util/security.js';
 import { readCredentialsSync } from './util/credentials.js';
 import { friendlyFsError } from './util/errors.js';
 import { atomicWrite } from './util/atomicWrite.js';
@@ -14,6 +14,7 @@ export const defaultConfig = {
     outDir: 'src/assets/magicpixel',
     include: ['**/*'],
     exclude: [],
+    connect: [],
     emitIndex: true,
 };
 export function configPath(cwd = process.cwd()) {
@@ -43,6 +44,7 @@ export async function loadConfig(cwd = process.cwd()) {
     }
     const include = normalizeGlobList(parsed.include ?? defaultConfig.include, 'include');
     const exclude = normalizeGlobList(parsed.exclude ?? defaultConfig.exclude, 'exclude');
+    const connect = normalizeGlobList(parsed.connect ?? defaultConfig.connect, 'connect');
     const rawOutDir = typeof parsed.outDir === 'string' && parsed.outDir.trim() ? parsed.outDir : defaultConfig.outDir;
     let outDir;
     try {
@@ -87,6 +89,7 @@ export async function loadConfig(cwd = process.cwd()) {
         unityPpu,
         unitySyncAll: parsed.unitySyncAll === true ? true : undefined,
         push: parsed.push === false ? false : undefined,
+        connect,
     };
 }
 const MAX_GLOBS = 64;
@@ -110,6 +113,10 @@ function normalizeGlobList(value, field) {
             throw new Error(`${CONFIG_FILENAME}: "${field}" entry is too long (>${MAX_GLOB_LEN} chars) or contains a null byte.\n` +
                 `  Fix: shorten the pattern.`);
         }
+        if (g.split(/[/\\]/).some((seg) => seg === '..')) {
+            throw new Error(`${CONFIG_FILENAME}: "${field}" must not contain ".." segments.\n` +
+                `  Fix: use a project-relative glob such as "Assets/Sprites/**".`);
+        }
         out.push(g);
     }
     return out;
@@ -143,7 +150,7 @@ export async function loadState(cwd = process.cwd()) {
         return {};
     }
     try {
-        return JSON.parse(raw);
+        return scrubLoadedState(JSON.parse(raw));
     }
     catch (e) {
         // Corrupt state file (truncated by a crash, hand-edited, disk full, etc.)
@@ -162,6 +169,27 @@ export async function loadState(cwd = process.cwd()) {
         return {};
     }
 }
+/** Drop untrusted persisted sourceRel so a hand-edited state.json cannot leak into later saves. */
+function scrubLoadedState(state) {
+    const synced = state.synced;
+    if (!synced || typeof synced !== 'object' || Array.isArray(synced))
+        return state;
+    const next = {};
+    for (const [key, val] of Object.entries(synced)) {
+        if (!val || typeof val !== 'object')
+            continue;
+        const sprite = { ...val };
+        if (sprite.sourceRel !== undefined) {
+            const safe = sanitizeSourceRel(sprite.sourceRel);
+            if (safe)
+                sprite.sourceRel = safe;
+            else
+                delete sprite.sourceRel;
+        }
+        next[key] = sprite;
+    }
+    return { ...state, synced: next };
+}
 export async function saveState(state, cwd = process.cwd()) {
     const path = statePath(cwd);
     try {

package/dist/index.js

@@ -14,6 +14,8 @@ import { logoutCommand } from './commands/logout.js';
 import { doctorCommand } from './commands/doctor.js';
 import { repairCommand } from './commands/repair.js';
 import { startCommand } from './commands/start.js';
+import { connectCommand } from './commands/connect.js';
+import { searchCommand } from './commands/search.js';
 import { parseWatchInterval, parseConcurrency } from './util/flagValidators.js';
 import { CLI_VERSION } from './version.js';
 // Node version guard
@@ -97,6 +99,16 @@ program
     .option('--flatten', 'Allow replacing multi-layer artboards with the flat local image')
     .addHelpText('after', '\nExamples:\n  $ magicpixel push --dry-run      # see what changed on disk\n  $ magicpixel push                # send local edits + new sprites\n')
     .action(wrap("push", async (opts) => pushCommand(opts)));
+program
+    .command('connect <glob>')
+    .description('Add a game-sprite glob to the working set and ingest matching PNGs')
+    .addHelpText('after', '\nExamples:\n  $ magicpixel connect \'assets/Sprites/Hero/**\'\n  $ magicpixel connect Runtime/UI/hud.png\n')
+    .action(wrap("connect", async (glob) => connectCommand(glob)));
+program
+    .command('search <query>')
+    .description('Search indexed game PNGs (no network)')
+    .addHelpText('after', '\nExamples:\n  $ magicpixel search hero\n')
+    .action(wrap("search", async (query) => searchCommand(query)));
 program
     .command('add <glob>')
     .description('Append a glob pattern to include')

package/dist/util/framework.js

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
+import { relative, resolve } from 'node:path';
 const ENGINE_KINDS = new Set(['Unity', 'Godot', 'GameMaker']);
 export function isEngineKind(kind) {
     return kind !== null && ENGINE_KINDS.has(kind);
@@ -38,11 +38,58 @@ async function detectJsKind(cwd) {
         return null;
     }
 }
+/**
+ * Case-insensitive child lookup, preserving the on-disk name. `existsSync` of
+ * a guessed `Assets` path is wrong on macOS (matches `assets` but keeps the
+ * wrong casing).
+ */
+export function resolveChild(cwd, logicalName, opts = {}) {
+    try {
+        const want = logicalName.toLowerCase();
+        for (const ent of readdirSync(cwd, { withFileTypes: true })) {
+            if (ent.name.toLowerCase() !== want)
+                continue;
+            if (opts.directory && !ent.isDirectory())
+                continue;
+            return resolve(cwd, ent.name);
+        }
+    }
+    catch {
+        /* unreadable cwd */
+    }
+    return null;
+}
+/** Case-insensitive child directory, preserving the on-disk name. */
+export function resolveChildDir(cwd, logicalName) {
+    return resolveChild(cwd, logicalName, { directory: true });
+}
+function hasMetaSidecar(dir) {
+    try {
+        return readdirSync(dir).some((name) => name.endsWith('.meta'));
+    }
+    catch {
+        return false;
+    }
+}
 function detectEngineKind(cwd) {
     if (existsSync(resolve(cwd, 'project.godot')))
         return 'Godot';
-    if (existsSync(resolve(cwd, 'ProjectSettings', 'ProjectVersion.txt')))
+    const projectSettings = resolveChildDir(cwd, 'ProjectSettings');
+    if (projectSettings && resolveChild(projectSettings, 'ProjectVersion.txt'))
+        return 'Unity';
+    const packages = resolveChildDir(cwd, 'Packages');
+    if (packages && resolveChild(packages, 'manifest.json'))
         return 'Unity';
+    // Assets/assets only counts with Unity .meta sidecars — a generic `assets/`
+    // folder in a Node repo is not a Unity project.
+    const assets = resolveChildDir(cwd, 'Assets');
+    if (assets && hasMetaSidecar(assets))
+        return 'Unity';
+    // Embedded UPM package: Editor/Runtime plus root .meta (kr-core has no
+    // ProjectSettings and often only a lowercase `assets` dump).
+    if (hasMetaSidecar(cwd) && (resolveChildDir(cwd, 'Editor') || resolveChildDir(cwd, 'Runtime'))) {
+        return 'Unity';
+    }
     try {
         const yyp = readdirSync(cwd).find((name) => name.endsWith('.yyp'));
         if (yyp)
@@ -79,17 +126,22 @@ export function suggestOutDir(kind, cwd = process.cwd()) {
         case 'TanStack Start':
             return 'src/assets/magicpixel';
         case 'Unity':
-            return 'Assets/MagicPixel';
+            return suggestEngineOutDir(cwd, 'Assets', 'MagicPixel');
         case 'Godot':
-            return 'assets/magicpixel';
+            return suggestEngineOutDir(cwd, 'assets', 'magicpixel');
         case 'GameMaker':
-            return 'datafiles/magicpixel';
+            return suggestEngineOutDir(cwd, 'datafiles', 'magicpixel');
         default:
             // No kind detected — prefer src/ if present so the typed index is
             // importable; otherwise fall back to a top-level assets/ dir.
             return existsSync(resolve(cwd, 'src')) ? 'src/assets/magicpixel' : 'assets/magicpixel';
     }
 }
+function suggestEngineOutDir(cwd, folder, destName) {
+    const found = resolveChildDir(cwd, folder);
+    const rel = found ? relative(cwd, found).replace(/\\/g, '/') : folder;
+    return `${rel || folder}/${destName}`;
+}
 export function hasPackageJson(cwd = process.cwd()) {
     return existsSync(resolve(cwd, 'package.json'));
 }