@magicpixelart/cli 0.5.7 → 0.5.9

package/dist/commands/start.js

@@ -14,25 +14,24 @@ import { cmd } from '../util/invoke.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 @magicpixelart/cli start` and end up with sprites on disk and a watch
- * script ready to run.
+ * can paste `npx @magicpixelart/cli start` and end up with game sprites in
+ * MagicPixel (and flagged sprites back on disk) plus a watch script.
  */
 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(kleur.dim('  This links your game project. Sprites are indexed locally; nothing is imported until you connect a working set.'));
     console.log();
-    // 1. `start` is JS-only — engine projects use init + login + sync --watch.
-    if (!hasPackageJson()) {
-        const kind = await detectProjectKind();
-        if (isEngineKind(kind)) {
-            console.log(kleur.yellow(`  Detected ${kind}. \`${cmd('start')}\` is JS-only; run ` +
-                `\`${cmd('init')} && ${cmd('login')} && ${cmd('sync')} --watch\` instead.`));
-            return;
-        }
-        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.'));
+    const kind = await detectProjectKind();
+    // Engine projects (including Unity UPM packages) have no package.json
+    // requirement. JS projects still need one.
+    if (!hasPackageJson() && !isEngineKind(kind)) {
+        console.log(kleur.yellow('  MagicPixel needs a game project to sync into.\n' +
+            '  Run this inside your Unity, Godot, GameMaker, or JavaScript folder\n' +
+            '  (Unity package, project with Assets/, or a folder with package.json).'));
         return;
     }
+    if (kind)
+        console.log(kleur.dim(`  Detected: ${kind}`));
     // 2. Run init non-interactively unless config already exists AND is valid.
     // A broken `magicpixel.json` (hand-edited / truncated) used to slip past
     // the existsSync check here and then explode deep inside `syncCommand`.
@@ -73,10 +72,21 @@ export async function startCommand(opts = {}) {
     // 5. First sync. syncCommand sets `process.exitCode = 1` on download
     //    failures without throwing — snapshot around the call so we don't
     //    print a misleading green "you're set up" over a half-failed run.
+    //    Manifest 546s throw after still importing local sprites; catch so
+    //    the watch instructions below aren't swallowed.
     console.log();
-    console.log(kleur.bold('Step: first sync'));
+    console.log(kleur.bold('Step: sync'));
     const exitBefore = process.exitCode ?? 0;
-    await syncCommand({ full: true });
+    try {
+        await syncCommand({ full: true });
+    }
+    catch (e) {
+        const err = e;
+        console.error(kleur.red(err.message ?? String(e)));
+        process.exitCode = 1;
+        const { reportCliError } = await import('../util/telemetry.js');
+        await reportCliError(err, { command: 'start' });
+    }
     const firstSyncFailed = (process.exitCode ?? 0) > exitBefore;
     // 6. Tell the user how to run the watch loop. If `init` couldn't patch
     //    package.json (non-standard layout, write-protected, etc.) the
@@ -99,6 +109,9 @@ export async function startCommand(opts = {}) {
         console.log(`  ${kleur.green('▶')} ${kleur.bold(`${cmd('sync')} --watch`)}   ${kleur.dim('# keeps sprites fresh while you edit them in MagicPixel')}`);
     }
     console.log();
+    console.log(kleur.dim(`  Find sprites with \`${cmd('search')} hero\`, then \`${cmd('connect')} 'assets/Sprites/**'\` to add a working set.`));
+    console.log(kleur.dim('  Connected sprites write back to their original game path. New MagicPixel art lands in outDir.'));
+    console.log();
     if (await hasDevScript()) {
         const watchCmd = hasWatch ? 'npm run magicpixel:watch' : `${cmd('sync')} --watch`;
         console.log(kleur.dim('  Tip: run your dev server and the watcher together with'));

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 { runPush } from './push.js';
 export async function syncCommand(opts) {
     // Sweep any leaked `<file>.<pid>.<hex>.tmp` files left behind by a prior
     // crashed/killed CLI run before they pile up. Runs once per CLI invocation
@@ -340,15 +343,43 @@ 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.
     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
@@ -364,25 +395,26 @@ 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);
         }
         if (filtered.noneFlagged) {
-            // Every artboard is explicitly opted out. Pruning here would delete the
-            // user's whole sprite folder off the back of an unchecked box, so bail
-            // out with a hint instead.
+            // Nothing flagged for pull — don't dump the library, and don't prune.
+            // Local sprites still go up so they appear in MagicPixel on connect.
             if (verbose) {
                 console.log();
-                console.log(kleur.yellow('! No artboards are flagged "Sync to Unity" — nothing to sync.'));
-                console.log(kleur.dim('  Fix: right-click an artboard in MagicPixel → "Sync to Unity",'));
-                console.log(kleur.dim('  or set "unitySyncAll": true in magicpixel.json to sync everything.'));
+                console.log(kleur.yellow('! No artboards are flagged "Sync to Unity" — nothing to pull.'));
+                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.'));
             }
-            return {
+            const empty = {
                 added: [],
                 modified: [],
                 removed: [],
@@ -392,6 +424,8 @@ async function runOnce(opts, runOpts = {}) {
                 bytesSaved: 0,
                 renamed: [],
             };
+            await maybePushLocalSprites(config.push, verbose, gameIndex);
+            return empty;
         }
         const skipped = manifest.length - filtered.entries.length;
         manifest = filtered.entries;
@@ -407,13 +441,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
@@ -448,14 +487,13 @@ async function runOnce(opts, runOpts = {}) {
     // delete files outside what the current manifest delta touches).
     const localPngs = await walkOutDirPngs(config.outDir);
     // Sprites created in Unity (or any PNG we never pulled) are pending a
-    // `magicpixel push`, not orphans — see prunePolicy.ts.
-    let pendingPush = [];
+    // push into MagicPixel, not orphans — see prunePolicy.ts.
     if (!since) {
         const trackedPaths = new Set(Object.keys(state.synced ?? {})
             .concat(Object.values(previousAssets))
             .map((key) => {
             try {
-                return assetDiskPathFromKey(config.outDir, key);
+                return pathForKey(key);
             }
             catch {
                 return '';
@@ -469,7 +507,6 @@ async function runOnce(opts, runOpts = {}) {
             isTracked: (p) => trackedPaths.has(p),
         });
         orphans = policy.orphans;
-        pendingPush = policy.pendingPush;
     }
     // Heuristic-rename fallback for incremental mode.
     //
@@ -516,15 +553,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 +582,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);
@@ -679,6 +727,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 +735,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)
@@ -730,7 +781,9 @@ async function runOnce(opts, runOpts = {}) {
     // 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 +793,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 +871,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 };
@@ -917,16 +981,27 @@ async function runOnce(opts, runOpts = {}) {
         printChanges(result, '  ', { includeRenames: renamed.length === 0 });
         if (renamed.length > 0)
             printRenames(renamed, { withHints: true });
-        if (pendingPush.length > 0) {
-            console.log();
-            console.log(kleur.yellow(`! ${pendingPush.length} local sprite${pendingPush.length === 1 ? '' : 's'} ${pendingPush.length === 1 ? 'is' : 'are'} not in MagicPixel yet — kept on disk.`));
-            console.log(kleur.dim(`  Fix: run \`${cmd('push')}\` to add them to your library.`));
-        }
     }
+    await maybePushLocalSprites(config.push, verbose, gameIndex);
     if (result.failed)
         process.exitCode = 1;
     return result;
 }
+async function maybePushLocalSprites(pushEnabled, verbose, gameIndex) {
+    if (pushEnabled === false)
+        return null;
+    try {
+        return await runPush({ quiet: !verbose, gameIndex });
+    }
+    catch (e) {
+        if (verbose) {
+            console.log();
+            console.log(kleur.yellow(`! could not push working-set sprites into MagicPixel: ${e.message}`));
+            console.log(kleur.dim(`  Fix: run \`${cmd('push')}\` once the connection is healthy.`));
+        }
+        return null;
+    }
+}
 const CHANGE_PRINT_CAP = 50;
 function printChanges(r, indent, opts = { includeRenames: true }) {
     const lines = [];

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 {
@@ -86,6 +88,8 @@ export async function loadConfig(cwd = process.cwd()) {
         emitIndex,
         unityPpu,
         unitySyncAll: parsed.unitySyncAll === true ? true : undefined,
+        push: parsed.push === false ? false : undefined,
+        connect,
     };
 }
 const MAX_GLOBS = 64;
@@ -109,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;
@@ -142,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.)
@@ -161,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'));
 }