@magicpixelart/cli 0.5.6 → 0.5.8

package/dist/commands/sync.js

@@ -11,11 +11,17 @@ import { assetDiskPath, assetDiskPathFromKey, pruneEmptyDirs, walkOutDirPngs } f
 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 { DEFAULT_UNITY_PPU, writeMissingUnityMetas } from '../util/unityMeta.js';
+import { filterUnityManifest } from '../util/unityFilter.js';
+import { selectFullSyncOrphans } from '../util/prunePolicy.js';
 import { runTmpJanitor } from '../util/tmpJanitor.js';
 import { friendlyFsError } from '../util/errors.js';
 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
@@ -180,14 +186,14 @@ async function watchLoop(opts) {
                     // support thread and we can correlate against edge function logs.
                     const idSuffix = apiErr?.requestId ? kleur.dim(` (request id: ${apiErr.requestId})`) : '';
                     console.log(`${kleur.dim(timestamp())} ${kleur.red('✗')} Your key looks invalid or rotated.${idSuffix}`);
-                    console.log(kleur.dim('   Fix: run `magicpixel login` (this watcher will keep retrying every 30s).'));
+                    console.log(kleur.dim(`   Fix: run \`${cmd('login')}\` (this watcher will keep retrying every 30s).`));
                 }
                 pausedForAuth = true;
                 consecutiveAuthFailures = decision.consecutiveAuthFailures;
                 backoffSec = decision.nextBackoffSec;
                 if (decision.giveUp) {
                     console.log(`${kleur.dim(timestamp())} ${kleur.red('✗')} Giving up after ${MAX_AUTH_FAILURES} consecutive auth failures.`);
-                    console.log(kleur.dim('   Fix: run `magicpixel login` with a fresh key, then restart the watcher.'));
+                    console.log(kleur.dim(`   Fix: run \`${cmd('login')}\` with a fresh key, then restart the watcher.`));
                     // Surface this to /admin/errors — persistent watcher auth failure
                     // means a key is mass-rejected (revoked, project deleted, edge
                     // misconfig) and we want visibility without waiting for a support
@@ -337,6 +343,64 @@ async function runOnce(opts, runOpts = {}) {
         spinner?.fail('Manifest fetch failed');
         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();
+    // 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.
+    const deselectedPaths = [];
+    // Sprites whose "Sync to Unity" flag the server omitted. Not downloaded
+    // (strict opt-in) but explicitly shielded from pruning: a transient server
+    // response must never delete art from someone's game project.
+    const unknownFlagPaths = new Set();
+    if (projectKind === 'Unity') {
+        const filtered = filterUnityManifest(manifest, { syncAll: config.unitySyncAll });
+        if (filtered.unknown.length > 0) {
+            console.log(kleur.yellow(`! ${filtered.unknown.length} artboard${filtered.unknown.length === 1 ? '' : 's'} came back without a "Sync to Unity" flag — skipped (existing files kept).`));
+            console.log(kleur.dim(`  Fix: re-run \`${cmd('sync')}\` in a moment, or upgrade with \`npm i -D @magicpixelart/cli@latest\`.`));
+        }
+        const unknownSet = new Set(filtered.unknown);
+        for (const entry of manifest) {
+            if (filtered.entries.includes(entry))
+                continue;
+            const p = assetDiskPath(config.outDir, entry);
+            if (unknownSet.has(entry)) {
+                unknownFlagPaths.add(p);
+                continue;
+            }
+            if (existsSync(p))
+                deselectedPaths.push(p);
+        }
+        if (filtered.noneFlagged) {
+            // 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 pull.'));
+                console.log(kleur.dim('  Existing game sprites will still be imported into MagicPixel.'));
+                console.log(kleur.dim('  Flag folders/artboards in the library to pull them back into Unity.'));
+            }
+            const empty = {
+                added: [],
+                modified: [],
+                removed: [],
+                unchanged: 0,
+                failed: 0,
+                bytesIn: 0,
+                bytesSaved: 0,
+                renamed: [],
+            };
+            await maybePushLocalSprites(config.push, verbose);
+            return empty;
+        }
+        const skipped = manifest.length - filtered.entries.length;
+        manifest = filtered.entries;
+        if (verbose && skipped > 0) {
+            console.log(kleur.dim(`  unity → ${skipped} artboard${skipped === 1 ? '' : 's'} not flagged for sync (skipped)`));
+        }
+    }
     // Detect renames: same id, different key vs prior snapshot.
     const renamed = [];
     for (const entry of manifest) {
@@ -385,8 +449,27 @@ async function runOnce(opts, runOpts = {}) {
     // still gated on `!since` to preserve incremental-mode safety (we never
     // 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
+    // push into MagicPixel, not orphans — see prunePolicy.ts.
     if (!since) {
-        orphans = localPngs.map((a) => a.abs).filter((p) => !remoteDiskPaths.has(p));
+        const trackedPaths = new Set(Object.keys(state.synced ?? {})
+            .concat(Object.values(previousAssets))
+            .map((key) => {
+            try {
+                return assetDiskPathFromKey(config.outDir, key);
+            }
+            catch {
+                return '';
+            }
+        })
+            .filter(Boolean));
+        const policy = selectFullSyncOrphans({
+            localPaths: localPngs.map((a) => a.abs),
+            remoteDiskPaths,
+            protectedPaths: unknownFlagPaths,
+            isTracked: (p) => trackedPaths.has(p),
+        });
+        orphans = policy.orphans;
     }
     // Heuristic-rename fallback for incremental mode.
     //
@@ -440,6 +523,10 @@ async function runOnce(opts, runOpts = {}) {
     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.
+    for (const p of deselectedPaths)
+        orphanSet.add(p);
     // Server-side rename history. Each manifest entry carries the composite
     // keys this row was previously emitted under (populated by the editor when
     // a doc/artboard is renamed). For each prior key whose file is still on
@@ -638,6 +725,19 @@ async function runOnce(opts, runOpts = {}) {
         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);
+        if (verbose && meta.written > 0) {
+            console.log(kleur.dim(`  unity → ${meta.written} .meta file${meta.written === 1 ? '' : 's'} written`));
+        }
+        if (verbose && meta.failed > 0) {
+            console.log(kleur.yellow(`  ! ${meta.failed} .meta file${meta.failed === 1 ? '' : 's'} could not be written — Unity will use default import settings.`));
+        }
+    }
     // Prune (now default — pass --no-prune to opt out).
     if (shouldPrune && orphans.length > 0) {
         const outRoot = resolve(process.cwd(), config.outDir);
@@ -645,6 +745,9 @@ async function runOnce(opts, runOpts = {}) {
             assertPathInsideRoot(p, outRoot, '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 key = relPath.endsWith('.png') ? relPath.slice(0, -4) : relPath;
                 result.removed.push(key);
@@ -708,7 +811,36 @@ async function runOnce(opts, runOpts = {}) {
                 delete nextAssets[id];
         }
     }
-    const nextState = { ...state, assets: nextAssets };
+    // Address book for `magicpixel push`: composite key → artboard + the sha we
+    // just put on disk. Keyed by key (not id) so a disk walk can look it up
+    // 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)
+        delete nextSynced[r.oldKey];
+    for (const key of result.removed)
+        delete nextSynced[key];
+    for (const entry of manifest) {
+        if (!entry.asset_id)
+            continue;
+        const sha = entry.sha256 ?? (await fileSha256(pathFor(entry)));
+        if (!sha)
+            continue;
+        // 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 };
+            continue;
+        }
+        nextSynced[entry.key] = {
+            assetId: entry.asset_id,
+            layerIdx: entry.layer_idx,
+            sha256: sha,
+            ...(typeof entry.layer_count === 'number' ? { layers: entry.layer_count } : {}),
+        };
+    }
+    const nextState = { ...state, assets: nextAssets, synced: nextSynced };
     if (result.failed === 0) {
         // Advance the cursor to the newest row we actually observed, NOT the
         // wall-clock time the sync started. Using startedAt silently skipped
@@ -786,10 +918,25 @@ async function runOnce(opts, runOpts = {}) {
         if (renamed.length > 0)
             printRenames(renamed, { withHints: true });
     }
+    await maybePushLocalSprites(config.push, verbose);
     if (result.failed)
         process.exitCode = 1;
     return result;
 }
+async function maybePushLocalSprites(pushEnabled, verbose) {
+    if (pushEnabled === false)
+        return;
+    try {
+        await runPush({ quiet: !verbose });
+    }
+    catch (e) {
+        if (verbose) {
+            console.log();
+            console.log(kleur.yellow(`! could not import local sprites into MagicPixel: ${e.message}`));
+            console.log(kleur.dim(`  Fix: run \`${cmd('push')}\` once the connection is healthy.`));
+        }
+    }
+}
 const CHANGE_PRINT_CAP = 50;
 function printChanges(r, indent, opts = { includeRenames: true }) {
     const lines = [];

package/dist/config.js

@@ -5,6 +5,7 @@ import { assertSafeOutDir, MAX_GLOB_LEN, validateEndpointUrl } from './util/secu
 import { readCredentialsSync } from './util/credentials.js';
 import { friendlyFsError } from './util/errors.js';
 import { atomicWrite } from './util/atomicWrite.js';
+import { cmd } from './util/invoke.js';
 const CONFIG_FILENAME = 'magicpixel.json';
 const STATE_DIR = '.magicpixel';
 const STATE_FILENAME = 'state.json';
@@ -25,7 +26,7 @@ export async function loadConfig(cwd = process.cwd()) {
     const path = configPath(cwd);
     if (!existsSync(path)) {
         throw new Error(`No ${CONFIG_FILENAME} found in ${cwd}.\n` +
-            `  Fix: run \`npx magicpixel init\` to create one.`);
+            `  Fix: run \`${cmd('start')}\` — it creates the config, logs you in, and runs the first sync.`);
     }
     const raw = await readFile(path, 'utf8');
     let parsed;
@@ -66,12 +67,26 @@ export async function loadConfig(cwd = process.cwd()) {
         }
         emitIndex = parsed.emitIndex;
     }
+    let unityPpu;
+    if (parsed.unityPpu !== undefined) {
+        if (typeof parsed.unityPpu !== 'number' ||
+            !Number.isFinite(parsed.unityPpu) ||
+            parsed.unityPpu <= 0 ||
+            parsed.unityPpu > 4096) {
+            throw new Error(`${CONFIG_FILENAME}: "unityPpu" must be a number between 1 and 4096.\n` +
+                `  Fix: set "unityPpu": 32 (or remove the field to use the default).`);
+        }
+        unityPpu = Math.round(parsed.unityPpu);
+    }
     return {
         outDir,
         include,
         exclude,
         endpoint,
         emitIndex,
+        unityPpu,
+        unitySyncAll: parsed.unitySyncAll === true ? true : undefined,
+        push: parsed.push === false ? false : undefined,
     };
 }
 const MAX_GLOBS = 64;
@@ -112,7 +127,7 @@ export async function saveConfig(config, cwd = process.cwd()) {
         throw friendlyFsError(e, {
             operation: 'Saving magicpixel.json',
             path,
-            hint: 'magicpixel.json holds your sync config — without it `magicpixel sync` can\'t run.',
+            hint: `magicpixel.json holds your sync config — without it \`${cmd('sync')}\` can't run.`,
         });
     }
 }
@@ -196,7 +211,7 @@ export function getApiKey() {
         throw new Error('No MagicPixel API key found.\n' +
             '  Fix:\n' +
             '    1. Get a key at https://magicpixel.art/settings (API Keys).\n' +
-            '    2. Run `magicpixel login` (or `export MAGICPIXEL_API_KEY=mp_live_...`).\n' +
+            `    2. Run \`${cmd('login')}\` (or \`export MAGICPIXEL_API_KEY=mp_live_...\`).\n` +
             '    3. Re-run the command.');
     }
     // Env vars from shells routinely smuggle in stray quotes / whitespace; the
@@ -209,7 +224,7 @@ export function getApiKey() {
     }
     if (!/^mp_(live|test)_[a-f0-9]{64}$/.test(trimmed)) {
         throw new Error(`MagicPixel API key does not look right (expected mp_live_… or mp_test_…).\n` +
-            `  Fix: run \`magicpixel login\` and paste a fresh key from https://magicpixel.art/settings.`);
+            `  Fix: run \`${cmd('login')}\` and paste a fresh key from https://magicpixel.art/settings.`);
     }
     return trimmed;
 }

package/dist/index.js

@@ -3,6 +3,7 @@ import { Command } from 'commander';
 import kleur from 'kleur';
 import { initCommand } from './commands/init.js';
 import { syncCommand } from './commands/sync.js';
+import { pushCommand } from './commands/push.js';
 import { addCommand } from './commands/add.js';
 import { removeCommand } from './commands/remove.js';
 import { listCommand } from './commands/list.js';
@@ -89,6 +90,13 @@ program
     .option('-c, --concurrency <n>', 'Parallel downloads (1–16, default 6)', parseConcurrency)
     .addHelpText('after', '\nExamples:\n  $ magicpixel sync                # incremental sync\n  $ magicpixel sync --full         # ignore lastSync, re-check everything\n  $ magicpixel sync -w             # watch mode (2s; adaptive idle backoff; exit 2 after 5 auth failures)\n')
     .action(wrap("sync", async (opts) => syncCommand(opts)));
+program
+    .command('push')
+    .description('Upload local sprite edits back to MagicPixel (two-way sync)')
+    .option('--dry-run', 'Print what would be pushed without sending anything')
+    .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('add <glob>')
     .description('Append a glob pattern to include')

package/dist/util/emitIndex.js

@@ -5,6 +5,7 @@ import { assertSafeAssetSegments } from './security.js';
 import { atomicWrite } from './atomicWrite.js';
 import { walkOutDirPngs } from './paths.js';
 import { isStaticOutDir } from './framework.js';
+import { cmd } from './invoke.js';
 const AGENT_HEADER = [
     '// 👋 AI agents: import sprites by key, e.g.',
     '//   import { MagicPixelAssets } from "<this-dir>";',
@@ -57,7 +58,7 @@ export async function emitTypedIndex(outDir, entries, cwd = process.cwd()) {
     }
     const lines = [
         '// AUTOGENERATED by @magicpixelart/cli. Do not edit.',
-        '// Re-runs of `magicpixel sync` overwrite this file.',
+        `// Re-runs of \`${cmd('sync')}\` overwrite this file.`,
         '//',
         AGENT_HEADER,
         '',
@@ -185,7 +186,7 @@ function renderAgentsSection(outDir) {
             `<img src={MagicPixelAssetsById["<asset-uuid>"]} />`,
             '```',
             '',
-            'When you rename or move an asset, `magicpixel sync` prints both the old → new key',
+            `When you rename or move an asset, \`${cmd('sync')}\` prints both the old → new key`,
             'and the matching `MagicPixelAssetsById[...]` hint so you can pick whichever you prefer.',
         ];
     return [

package/dist/util/gameScan.js

@@ -0,0 +1,119 @@
+/**
+ * First-connect import: when `outDir` has no PNGs yet, copy nearby game
+ * sprites into it so `push` can adopt them into the MagicPixel library.
+ *
+ * Only engine projects. Never walks Library/Temp/Packages. Never overwrites
+ * a file already in outDir. Capped so a huge Assets/ tree can't stampede
+ * the library.
+ */
+import { existsSync } from 'node:fs';
+import { copyFile, mkdir, readdir } from 'node:fs/promises';
+import { dirname, relative, resolve } from 'node:path';
+import { isEngineKind } from './framework.js';
+import { assertPathInsideRoot } from './security.js';
+/** Unity/engine folders that are never sprite sources. */
+export const GAME_SCAN_SKIP_DIRS = new Set([
+    'library',
+    'temp',
+    'obj',
+    'logs',
+    'packages',
+    'projectsettings',
+    'usersettings',
+    'streamingassets',
+]);
+export const MAX_GAME_IMPORT = 200;
+export function gameScanRoot(kind) {
+    switch (kind) {
+        case 'Unity':
+            return 'Assets';
+        case 'Godot':
+            return 'assets';
+        case 'GameMaker':
+            return 'datafiles';
+        default:
+            return null;
+    }
+}
+/**
+ * Copy PNGs from the engine asset root into `outDir`, preserving relative
+ * paths. No-op when `outDir` already has PNGs, when the project isn't an
+ * engine, or when the scan root is missing.
+ */
+export async function importNearbyGamePngs(outDir, kind, cwd = process.cwd()) {
+    const result = { copied: 0, skipped: 0, capped: false };
+    if (!isEngineKind(kind))
+        return result;
+    const scanRel = gameScanRoot(kind);
+    if (!scanRel)
+        return result;
+    const scanRoot = resolve(cwd, scanRel);
+    const destRoot = resolve(cwd, outDir);
+    if (!existsSync(scanRoot))
+        return result;
+    const destNorm = destRoot.replace(/\\/g, '/').toLowerCase();
+    const found = [];
+    await walkPngs(scanRoot, scanRoot, destNorm, found);
+    if (found.length >= MAX_GAME_IMPORT)
+        result.capped = true;
+    if (found.length > MAX_GAME_IMPORT)
+        found.length = MAX_GAME_IMPORT;
+    for (const abs of found) {
+        const rel = relative(scanRoot, abs).replace(/\\/g, '/');
+        const dest = resolve(destRoot, rel);
+        try {
+            assertPathInsideRoot(dest, destRoot, 'outDir');
+        }
+        catch {
+            result.skipped++;
+            continue;
+        }
+        if (existsSync(dest)) {
+            result.skipped++;
+            continue;
+        }
+        await mkdir(dirname(dest), { recursive: true });
+        await copyFile(abs, dest);
+        result.copied++;
+    }
+    return result;
+}
+async function walkPngs(dir, root, destNorm, out) {
+    if (out.length >= MAX_GAME_IMPORT)
+        return;
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const ent of entries) {
+        if (out.length >= MAX_GAME_IMPORT)
+            return;
+        if (ent.isSymbolicLink())
+            continue;
+        const full = resolve(dir, ent.name);
+        try {
+            assertPathInsideRoot(full, root, 'scan');
+        }
+        catch {
+            continue;
+        }
+        if (ent.isDirectory()) {
+            const name = ent.name.toLowerCase();
+            if (name.startsWith('.'))
+                continue;
+            if (GAME_SCAN_SKIP_DIRS.has(name))
+                continue;
+            // Don't re-import from outDir if it sits inside the scan root
+            // (Assets/MagicPixel under Assets/).
+            if (full.replace(/\\/g, '/').toLowerCase() === destNorm)
+                continue;
+            await walkPngs(full, root, destNorm, out);
+        }
+        else if (ent.isFile() && ent.name.toLowerCase().endsWith('.png')) {
+            out.push(full);
+        }
+    }
+}

package/dist/util/invoke.js

@@ -0,0 +1,47 @@
+/**
+ * How should we tell the user to run a subcommand?
+ *
+ * `magicpixel` is only the BIN name; the published package is
+ * `@magicpixelart/cli`. So npx-ing the bin name directly (e.g. `magicpixel init` via npx) 404s in a
+ * project with no local install ("'magicpixel@*' is not in this registry"), which is a dead end
+ * for anyone driving the CLI purely through `npx @magicpixelart/cli …`.
+ *
+ * Rule: if the package resolves from the project's node_modules, the bin is on
+ * the PATH for `npx`/scripts and the short `magicpixel <cmd>` form works.
+ * Otherwise we print the always-correct `npx @magicpixelart/cli <cmd>` form.
+ * When in doubt we prefer the long form — it works in both worlds.
+ */
+import { createRequire } from 'node:module';
+import { resolve } from 'node:path';
+export const PKG_NAME = '@magicpixelart/cli';
+let cachedLocal = null;
+/** True when `@magicpixelart/cli` is installed in the current project. */
+export function hasLocalInstall(cwd = process.cwd()) {
+    if (cachedLocal !== null)
+        return cachedLocal;
+    let local = false;
+    try {
+        // Resolve as if requiring from <cwd>/index.js so only the project's
+        // node_modules chain counts — not the npx cache this process runs from.
+        const req = createRequire(resolve(cwd, 'index.js'));
+        req.resolve(`${PKG_NAME}/package.json`);
+        local = true;
+    }
+    catch {
+        local = false;
+    }
+    cachedLocal = local;
+    return local;
+}
+/** Reset the memoized probe (tests only). */
+export function resetInvokeCache() {
+    cachedLocal = null;
+}
+/**
+ * Format a runnable command hint, e.g. `cmd('login')` →
+ * "npx @magicpixelart/cli login" or "magicpixel login".
+ */
+export function cmd(subcommand, cwd) {
+    const suffix = subcommand ? ` ${subcommand}` : '';
+    return hasLocalInstall(cwd) ? `magicpixel${suffix}` : `npx ${PKG_NAME}${suffix}`;
+}

package/dist/util/prunePolicy.js

@@ -0,0 +1,33 @@
+/**
+ * Which local PNGs a full sync is allowed to delete.
+ *
+ * Pruning used to be "anything on disk the manifest didn't mention". Two-way
+ * Unity sync breaks that assumption in two directions:
+ *
+ *   - Strict Unity opt-in excludes entries whose `unity` flag the server
+ *     omitted (older edge deploy, work-budget-starved manifest backfill). Those
+ *     are "unknown", not "unwanted" — deleting their sprite because of a
+ *     transient server response would be data loss inside someone's game
+ *     project. They're protected instead.
+ *   - Sprites authored in Unity have no manifest entry until `magicpixel push`
+ *     adopts them. They're pending, not orphaned.
+ *
+ * Everything we HAVE synced before (it's in `state.synced`) and that the
+ * manifest no longer references is a genuine orphan and still prunes: renames,
+ * deletions, and un-checked "Sync to Unity" boxes all keep working.
+ */
+export function selectFullSyncOrphans({ localPaths, remoteDiskPaths, protectedPaths, isTracked, }) {
+    const orphans = [];
+    const pendingPush = [];
+    for (const p of localPaths) {
+        if (remoteDiskPaths.has(p))
+            continue;
+        if (protectedPaths?.has(p))
+            continue;
+        if (isTracked(p))
+            orphans.push(p);
+        else
+            pendingPush.push(p);
+    }
+    return { orphans, pendingPush };
+}

package/dist/util/pushPlan.js

@@ -0,0 +1,80 @@
+/**
+ * Plan a disk → MagicPixel push.
+ *
+ * Pure so the decision table (skip / update / adopt / needs-flatten) is unit
+ * testable without touching the network or the filesystem.
+ *
+ * Two shapes reach the server:
+ *   - UPDATE: the key is in the sync state, so we know the exact artboard and
+ *     the composite sha we last wrote. A changed disk sha means a local edit.
+ *   - ADOPT:  the key is new on disk (a sprite someone created in Unity), so
+ *     the server mirrors the folders into the library and appends/creates the
+ *     document.
+ */
+/**
+ * Slug rule mirrored from the server (`slugify` + `SEGMENT_RE` in
+ * `src/lib/integration/artboardComposite.server.ts`). The server is the
+ * authority; this copy only exists so the CLI can pre-validate a path before
+ * spending a request, and `pushPlan.test.ts` pins the two together.
+ */
+export function pushSlug(raw) {
+    return raw
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 64)
+        .replace(/-+$/g, '');
+}
+export const MAX_PUSH_PATH_SEGMENTS = 8;
+export function planPush(candidates, synced, opts = {}) {
+    const state = synced ?? {};
+    const out = [];
+    for (const c of candidates) {
+        const known = state[c.key];
+        if (known) {
+            if (known.sha256 === c.diskSha256) {
+                out.push({ kind: 'skip', key: c.key, reason: 'unchanged' });
+                continue;
+            }
+            // Legacy row: the cloud has no addressable artboard, and adopting would
+            // duplicate art that already exists in the library.
+            if (known.legacy) {
+                out.push({ kind: 'skip', key: c.key, reason: 'legacy' });
+                continue;
+            }
+            if (!opts.flatten && typeof known.layers === 'number' && known.layers > 1) {
+                out.push({ kind: 'needs-flatten', key: c.key, layers: known.layers });
+                continue;
+            }
+            out.push({
+                kind: 'update',
+                key: c.key,
+                assetId: known.assetId,
+                layerIdx: known.layerIdx,
+                baseSha256: known.sha256,
+            });
+            continue;
+        }
+        // New on disk → adopt. A single segment (outDir/hero.png) is a document
+        // with one artboard of the same name — the server already accepts that.
+        const rawNames = c.segments.slice(-MAX_PUSH_PATH_SEGMENTS);
+        let pathNames = rawNames;
+        let path = pathNames.map(pushSlug);
+        if (path.length === 1 && path[0]) {
+            pathNames = [pathNames[0], pathNames[0]];
+            path = [path[0], path[0]];
+        }
+        if (path.length < 2 || path.some((s) => !s)) {
+            out.push({ kind: 'skip', key: c.key, reason: 'unusable-path' });
+            continue;
+        }
+        out.push({
+            kind: 'adopt',
+            key: c.key,
+            path,
+            pathNames,
+            name: pathNames[pathNames.length - 1],
+        });
+    }
+    return out;
+}

package/dist/util/unityFilter.js

@@ -0,0 +1,25 @@
+/**
+ * Per-artboard Unity sync opt-in (strict).
+ *
+ * In the editor, each artboard has a "Sync to Unity" checkbox (and library
+ * folders have a folder-level switch that cascades). A project may hold 100
+ * drafts but only 3 artboards that belong in the Unity project, so the CLI
+ * mirrors the in-app sync button and pulls ONLY the flagged ones.
+ *
+ * Strict opt-in: `unity === true` syncs, anything else does not. A missing
+ * flag means the server didn't say (older edge deploy, or a budget-starved
+ * manifest backfill) — those entries are excluded and reported via
+ * `unknownFlags` so the caller can warn instead of silently syncing the whole
+ * library into someone's game project.
+ */
+export function filterUnityManifest(manifest, opts = {}) {
+    if (opts.syncAll)
+        return { entries: manifest, noneFlagged: false, unknown: [] };
+    const entries = manifest.filter((e) => e.unity === true);
+    const unknown = manifest.filter((e) => typeof e.unity !== 'boolean');
+    return {
+        entries,
+        noneFlagged: manifest.length > 0 && entries.length === 0,
+        unknown,
+    };
+}