@magicpixelart/cli 0.5.8 → 0.5.9

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';
@@ -341,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
@@ -365,11 +395,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 +411,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 +424,7 @@ async function runOnce(opts, runOpts = {}) {
                 bytesSaved: 0,
                 renamed: [],
             };
-            await maybePushLocalSprites(config.push, verbose);
+            await maybePushLocalSprites(config.push, verbose, gameIndex);
             return empty;
         }
         const skipped = manifest.length - filtered.entries.length;
@@ -409,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
@@ -456,7 +493,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 +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 };
@@ -918,23 +982,24 @@ async function runOnce(opts, runOpts = {}) {
         if (renamed.length > 0)
             printRenames(renamed, { withHints: true });
     }
-    await maybePushLocalSprites(config.push, verbose);
+    await maybePushLocalSprites(config.push, verbose, gameIndex);
     if (result.failed)
         process.exitCode = 1;
     return result;
 }
-async function maybePushLocalSprites(pushEnabled, verbose) {
+async function maybePushLocalSprites(pushEnabled, verbose, gameIndex) {
     if (pushEnabled === false)
-        return;
+        return null;
     try {
-        await runPush({ quiet: !verbose });
+        return await runPush({ quiet: !verbose, gameIndex });
     }
     catch (e) {
         if (verbose) {
             console.log();
-            console.log(kleur.yellow(`! could not import local sprites into MagicPixel: ${e.message}`));
+            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;

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'));
 }