@magicpixelart/cli 0.5.28 → 0.5.31

package/CHANGELOG.md

@@ -5,8 +5,38 @@ All notable changes to `@magicpixelart/cli` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.5.31] - 2026-10-01
+
+### Added
+- `sync --only <folder>` (repeatable; or `"syncOnly": [...]` in magicpixel.json) limits push, pull and pruning to those game folders — e.g. `sync --watch --only Runtime/Sprites/Entities/decorations`. Everything else is left untouched. Changing the scope triggers one full pass.
+
+### Changed
+- `sync <folder>` now errors and suggests `--only` instead of silently syncing the whole project.
+- With `--only`, the legacy-folder sweep never touches folders outside the scope, and `--watch` on a folder that matches nothing exits once with a clear message instead of erroring every tick.
+
+### Fixed
+- Syncing an already-synced game folder to a new account/key/project no longer skips every sprite as "unchanged": the upload record now remembers its project and resets when the project changes (game files untouched).
+
+## [0.5.30] - 2026-10-01
+
+### Changed
+- `start` now checks the saved or environment key before syncing; a rejected saved key re-opens the key prompt instead of failing every request with 401.
+- `start` asks "all sprites, or one folder?" on game projects; `--folder <path>` answers it up front.
+- Rejected-key errors point to `login` first.
+
 ## [Unreleased]
 
+## [0.5.29]
+
+### Fixed
+- Ship `magicpixel resync <folder>`: the npm 0.5.28 build was published before the command landed.
+
+## [0.5.28]
+
+### Added
+- `magicpixel resync <folder>` (`--dry-run`, `--yes`): make one MagicPixel folder match the local game folder. Local files overwrite their MagicPixel copies (size follows the file); files missing locally move to Trash. Nothing is trashed if any upload fails or the game scan was capped.
+- `sync --watch` runs "Resync from game…" requests queued from the library folder menu.
+
 ## [0.5.27] — 2026-09-21
 
 - Fixed Sync presses that changed only an artboard selection being skipped as

package/README.md

@@ -32,7 +32,7 @@ Then leave this running while you work:
 npx @magicpixelart/cli sync --watch
 ```
 
-After `npm i -D @magicpixelart/cli` you can type `magicpixel sync --watch`. Connected sprites write back to their original game path. New MagicPixel-only art still lands in `outDir`. To sync only some folders: `npx @magicpixelart/cli connect 'assets/Sprites/**'`.
+After `npm i -D @magicpixelart/cli` you can type `magicpixel sync --watch`. Connected sprites write back to their original game path. New MagicPixel-only art still lands in `outDir`. To sync only some folders: `npx @magicpixelart/cli connect 'assets/Sprites/**'`. To watch just one folder of a huge project: `npx @magicpixelart/cli sync --watch --only Assets/Sprites/Enemies`.
 
 When it finishes:
 
@@ -112,6 +112,7 @@ No bundler config, no runtime, no extra package.
 | `repair [--dry-run] [-y]` | Self-heal a broken sync: validate key → quarantine `state.json` → prune empty dirs → full re-sync. |
 | `sync [...flags]` | Two-way: pull MagicPixel edits and push changed game sprites. |
 | `push [--dry-run] [--flatten]` | Upload local PNG edits (and connected game sprites) back to MagicPixel. |
+| `resync <folder> [--dry-run] [-y]` | Local files win for one folder: overwrite MagicPixel copies, move cloud-only files to Trash. |
 | `connect <glob>` | Limit which game folders sync (default is all sprites on Unity/Godot/GameMaker). |
 | `search <query>` | Search indexed game PNGs (no network). |
 | `add <glob>` / `remove <glob>` | Manage `include` patterns. |
@@ -129,6 +130,7 @@ No bundler config, no runtime, no extra package.
 | `--full` | Ignore `lastSync`; re-fetch the full manifest. |
 | `-c, --concurrency <n>` | Parallel downloads (1–16, default 6). |
 | `-q, --quiet` | Minimal output (for CI). |
+| `--only <folder...>` | Only push, pull and prune inside these game folders (repeatable). Everything else is left untouched. |
 
 Each successful sync prints a per-file change list (`+` added, `~` modified, `↪` renamed, `-` pruned) so you (and any AI agent reading the logs) know exactly what to wire up.
 
@@ -140,6 +142,14 @@ Sync is built to be cheap: a no-op run is one small manifest request, zero PNG b
 - Atomic writes (`*.tmp` → `rename`) survive crashes mid-write.
 - Retry with backoff on 429/5xx; `lastSync` only advances on a clean run.
 
+### Sync one folder of a big project
+
+```bash
+npx @magicpixelart/cli sync --watch --only Runtime/Sprites/Entities/decorations
+```
+
+Only that folder is pushed, pulled, or pruned. Every other file stays exactly as it is. Repeat `--only` for more folders, or set `"syncOnly"` in `magicpixel.json`. Changing the folder list triggers one full check. `sync <folder>` without `--only` stops with an error instead of syncing everything.
+
 ## Config (`magicpixel.json`)
 
 | Field      | Type       | Default                 | Meaning                                          |
@@ -151,6 +161,7 @@ Sync is built to be cheap: a no-op run is one small manifest request, zero PNG b
 | `emitIndex`| `boolean`  | `true`                  | Emit `<outDir>/index.ts` with typed asset map.   |
 | `unityPpu` | `number?`  | `32`                    | Unity only: pixels-per-unit in generated `.meta`. |
 | `push`     | `boolean?` | `true`                  | Upload local PNG changes (outDir + `connect` working set) to MagicPixel on every `sync`. Set `false` for pull-only. |
+| `syncOnly` | `string[]?` | — | Default for `sync --only`: folders a plain `sync` is limited to. |
 | `endpoint` | `string?`  | production URL          | Override the API base (testing only). Must be **HTTPS**. |
 
 State (`.magicpixel/state.json`) tracks `lastSync` (file mode `0600`). Add `.magicpixel/` to `.gitignore` (init offers to do this).

package/dist/api.js

@@ -92,7 +92,7 @@ export function errorCodeFromResponse(res) {
 export function friendlyApiError(status, body, context, code) {
     if (status === 401 || status === 403) {
         return (`${context}: ${status} — API key rejected.\n` +
-            `  Fix: regenerate at https://magicpixel.art/settings and re-run \`${cmd('login')}\`.`);
+            `  Fix: run \`${cmd('login')}\` and paste a fresh key from https://magicpixel.art/settings.`);
     }
     if (status === 404) {
         return (`${context}: 404 — endpoint or asset not found.\n` +
@@ -449,3 +449,29 @@ export async function pushSpritesAdaptive(sprites, retryOpts) {
         }
     }
 }
+// ---------- folder resync (local folder is the source of truth) -------------
+export function resolveResyncEndpoint() {
+    return resolveIngestEndpoint().replace(/\/ingest$/, '/resync');
+}
+async function postResync(body) {
+    const url = resolveResyncEndpoint();
+    return retryTransient('resync', async () => {
+        const { headers, requestId } = buildHeaders({ 'Content-Type': 'application/json' });
+        const res = await safeFetch(url, { method: 'POST', headers, body: JSON.stringify(body) });
+        const serverRequestId = res.headers.get('x-request-id') ?? requestId;
+        if (res.ok)
+            return (await res.json());
+        const text = await res.text();
+        throw new ApiError(res.status, withRequestId(friendlyApiError(res.status, text, 'resync', errorCodeFromResponse(res)), serverRequestId), serverRequestId);
+    });
+}
+export function pruneResyncFolder(folderPath, keepAssetIds, dryRun) {
+    return postResync({ action: 'prune', folderPath, keepAssetIds, dryRun });
+}
+export async function claimResyncRequest() {
+    const r = await postResync({ action: 'claim' });
+    return r.request ?? null;
+}
+export async function reportResyncRequest(id, status, message, counts) {
+    await postResync({ action: 'report', id, status, message, counts });
+}

package/dist/commands/push.js

@@ -10,9 +10,9 @@ import kleur from 'kleur';
 import ora from 'ora';
 import { mkdir, readFile, rename } from 'node:fs/promises';
 import { dirname, relative, resolve } from 'node:path';
-import { loadConfig, loadState, saveState } from '../config.js';
+import { loadConfig, loadState, saveState, resetStateIfProjectChanged, PROJECT_CHANGED_MESSAGE } from '../config.js';
 import { ensureEngineConnect } from '../util/engineConnect.js';
-import { PUSH_BATCH_SIZE, pushSpritesAdaptive } from '../api.js';
+import { PUSH_BATCH_SIZE, pushSpritesAdaptive, fetchManifestPage, getLastProjectInfo } from '../api.js';
 import { hashFile } from '../util/hash.js';
 import { createLimit } from '../util/limit.js';
 import { assetDiskPathFromKey, walkOutDirPngs } from '../util/paths.js';
@@ -37,11 +37,26 @@ export async function pushCommand(opts = {}) {
 export async function runPush(opts = {}) {
     const config = await ensureEngineConnect(await loadConfig(), process.cwd(), !opts.dryRun);
     const state = await loadState();
+    // Standalone push has no manifest yet — one tiny page tells us which project
+    // this key writes to, so a record from another account can't skip everything.
+    if (!opts.nestedSync && Object.keys(state.synced ?? {}).length > 0) {
+        const page = await fetchManifestPage({ config, limit: 1 });
+        if (resetStateIfProjectChanged(state, getLastProjectInfo()?.id, page.items.length === 0)) {
+            if (!opts.dryRun)
+                await saveState(state);
+            if (!opts.quiet)
+                console.log(kleur.yellow(`! ${PROJECT_CHANGED_MESSAGE}`));
+        }
+    }
     return runPushWith(config, state, opts);
 }
 export async function runPushWith(config, state, opts = {}) {
     const quiet = opts.quiet === true;
-    const empty = { created: 0, updated: 0, unchanged: 0, conflict: 0, error: 0, imported: 0 };
+    if (opts.replace)
+        opts = { ...opts, flatten: true };
+    const empty = {
+        created: 0, updated: 0, unchanged: 0, conflict: 0, error: 0, imported: 0, keptAssetIds: [], scanned: 0,
+    };
     const spinner = quiet ? null : ora(countingSpritesText(0)).start();
     const kind = await detectProjectKind();
     const index = opts.gameIndex
@@ -110,7 +125,7 @@ export async function runPushWith(config, state, opts = {}) {
         const segments = entry
             ? entry.adoptRel.replace(/\.png$/i, '').split('/')
             : key.split('/');
-        if (opts.excludeKeys?.has(key)) {
+        if (opts.excludeKeys?.has(key) || (opts.keyFilter && !opts.keyFilter(key))) {
             reportHash();
             return;
         }
@@ -129,7 +144,7 @@ export async function runPushWith(config, state, opts = {}) {
         if (sourceByKey.has(k))
             folderTreeKeys.add(k);
     }
-    const actions = planPush(candidates, state.synced, { flatten: opts.flatten, folderTreeKeys });
+    const actions = planPush(candidates, state.synced, { flatten: opts.flatten, folderTreeKeys, replace: opts.replace });
     const skipped = actions.filter((a) => a.kind === 'skip' && a.reason !== 'legacy').length;
     const legacy = actions.filter((a) => a.kind === 'skip' && a.reason === 'legacy');
     const flattenBlocked = actions.filter((a) => a.kind === 'needs-flatten');
@@ -162,7 +177,10 @@ export async function runPushWith(config, state, opts = {}) {
         await persistDiskFingerprints(state, candidates);
         if (!quiet)
             console.log(kleur.green('✓ nothing to push.'));
-        return { ...empty, imported: matched.entries.length, unchanged: skipped };
+        return {
+            ...empty, imported: matched.entries.length, unchanged: skipped,
+            keptAssetIds: collectKeptAssetIds(candidates, state.synced ?? {}, []), scanned: candidates.length,
+        };
     }
     if (opts.dryRun) {
         if (!quiet) {
@@ -173,7 +191,10 @@ export async function runPushWith(config, state, opts = {}) {
             }
             console.log(kleur.dim('--dry-run: nothing sent.'));
         }
-        return { ...empty, imported: matched.entries.length };
+        return {
+            ...empty, imported: matched.entries.length,
+            keptAssetIds: collectKeptAssetIds(candidates, state.synced ?? {}, []), scanned: candidates.length,
+        };
     }
     const outRoot = resolve(process.cwd(), config.outDir);
     const shaByKey = new Map(candidates.map((c) => [c.key, c.diskSha256]));
@@ -195,10 +216,14 @@ export async function runPushWith(config, state, opts = {}) {
                 layerIdx: a.layerIdx,
                 baseSha256: a.baseSha256,
                 flatten: opts.flatten === true,
+                ...(opts.replace ? { replace: true } : {}),
             });
         }
         else if (a.kind === 'adopt') {
-            sprites.push({ key: a.key, pngBase64, diskSha256, path: a.path, pathNames: a.pathNames, name: a.name });
+            sprites.push({
+                key: a.key, pngBase64, diskSha256, path: a.path, pathNames: a.pathNames, name: a.name,
+                ...(opts.replace ? { replace: true } : {}),
+            });
         }
     }
     const progress = quiet ? null : ora(`Pushing 0/${sprites.length}…`).start();
@@ -296,7 +321,27 @@ export async function runPushWith(config, state, opts = {}) {
     }
     if (failed)
         process.exitCode = 1;
-    return { ...counts, imported: matched.entries.length };
+    return {
+        ...counts, imported: matched.entries.length,
+        keptAssetIds: collectKeptAssetIds(candidates, synced, results), scanned: candidates.length,
+    };
+}
+/**
+ * Library documents that now mirror an in-scope local file: every successful
+ * push result, plus unchanged candidates already recorded in sync state.
+ */
+export function collectKeptAssetIds(candidates, synced, results) {
+    const out = new Set();
+    for (const r of results) {
+        if (r.assetId && (r.status === 'created' || r.status === 'updated' || r.status === 'unchanged'))
+            out.add(r.assetId);
+    }
+    for (const c of candidates) {
+        const id = synced[c.key]?.assetId;
+        if (id)
+            out.add(id);
+    }
+    return [...out];
 }
 /**
  * Sprites to re-send under `--force`: every sprite the cloud refused because it

package/dist/commands/resync.js

@@ -0,0 +1,123 @@
+/**
+ * `magicpixel resync <folder>` — make one MagicPixel library folder match the
+ * local game folder exactly:
+ *   - every local sprite in the folder overwrites its MagicPixel copy (size
+ *     follows the file, MagicPixel-only edits are replaced);
+ *   - new local sprites are imported;
+ *   - MagicPixel files in that folder with no local file go to Trash.
+ */
+import kleur from 'kleur';
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import { loadConfig, loadState } from '../config.js';
+import { ensureEngineConnect } from '../util/engineConnect.js';
+import { detectProjectKind, isEngineKind } from '../util/framework.js';
+import { indexGamePngs, countingSpritesText } from '../util/gameScan.js';
+import { pruneResyncFolder } from '../api.js';
+import { runPushWith } from './push.js';
+/** Same slug rules as library folders / manifest keys. */
+export function slugifySegment(input) {
+    return input.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+export function parseFolderArg(folder) {
+    return folder
+        .replace(/\\/g, '/')
+        .split('/')
+        .map((s) => slugifySegment(s.trim()))
+        .filter(Boolean);
+}
+/**
+ * True when `key` (`<folders…>/<doc>/<artboard>`) lives inside `segments`.
+ * Only the folder part of the key counts, so resyncing `enemies` never touches
+ * a root document that happens to be named "enemies".
+ */
+export function keyInFolder(key, segments) {
+    const parts = key.split('/');
+    const folderParts = parts.slice(0, Math.max(0, parts.length - 2));
+    if (folderParts.length < segments.length)
+        return false;
+    return segments.every((s, i) => folderParts[i] === s);
+}
+async function confirm(prompt) {
+    if (!stdin.isTTY)
+        return false;
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+        const a = (await rl.question(prompt)).trim().toLowerCase();
+        return a === 'y' || a === 'yes';
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function resyncCommand(folder, opts = {}) {
+    await runResync(parseFolderArg(folder), opts);
+}
+export async function runResync(segments, opts = {}) {
+    if (segments.length === 0) {
+        throw new Error('Pass a folder, e.g. `magicpixel resync Sprites/Enemies`. Resyncing the whole project is `push --force`.');
+    }
+    const log = (m) => { if (!opts.quiet)
+        console.log(m); };
+    const config = await ensureEngineConnect(await loadConfig(), process.cwd(), !opts.dryRun);
+    const kind = await detectProjectKind();
+    if (!isEngineKind(kind))
+        throw new Error('This folder is not a Unity/Godot/GameMaker project.');
+    const gameIndex = await indexGamePngs(kind, process.cwd(), config.outDir, {
+        onProgress: opts.quiet ? undefined : (p) => { stdout.write(`\r${countingSpritesText(p)}`); },
+    });
+    if (!opts.quiet)
+        stdout.write('\n');
+    const keyFilter = (key) => keyInFolder(key, segments);
+    const label = segments.join('/');
+    // Plan first: what would change, and what would go to Trash.
+    const plan = await runPushWith(config, await loadState(), {
+        dryRun: true, replace: true, keyFilter, gameIndex, quiet: true,
+    });
+    if (plan.scanned === 0) {
+        throw new Error(`No local sprites found in "${label}". Nothing was changed. Check the folder name with \`magicpixel search\`.`);
+    }
+    const pruneAllowed = !gameIndex.capped;
+    const preview = pruneAllowed && plan.keptAssetIds.length > 0
+        ? await pruneResyncFolder(segments, plan.keptAssetIds, true)
+        : null;
+    log(kleur.bold(`Resync ${label} from your game`));
+    log(`  local sprites: ${plan.scanned}`);
+    if (preview) {
+        log(`  to trash in MagicPixel (no local file): ${preview.wouldTrash.length}`);
+        for (const n of preview.wouldTrash.slice(0, 10))
+            log(kleur.dim(`    - ${n}`));
+        if (preview.wouldTrash.length > 10)
+            log(kleur.dim(`    …and ${preview.wouldTrash.length - 10} more`));
+    }
+    if (!pruneAllowed)
+        log(kleur.yellow('  ! game scan hit its file cap — nothing will be trashed.'));
+    log(kleur.dim('  Local files win: MagicPixel copies are overwritten and resized to match.'));
+    if (opts.dryRun) {
+        log(kleur.dim('--dry-run: nothing sent.'));
+        return { push: plan, trashed: 0, pruneSkipped: 'dry-run' };
+    }
+    if (!opts.yes && !(await confirm('Continue? (y/N) '))) {
+        throw new Error('Cancelled. Re-run with --yes to skip this question.');
+    }
+    const push = await runPushWith(config, await loadState(), {
+        replace: true, keyFilter, gameIndex, quiet: opts.quiet,
+    });
+    let pruneSkipped = null;
+    let trashed = 0;
+    if (!pruneAllowed)
+        pruneSkipped = 'game scan capped';
+    else if (push.error > 0 || push.conflict > 0)
+        pruneSkipped = 'some sprites failed to upload';
+    else if (push.keptAssetIds.length === 0)
+        pruneSkipped = 'no files confirmed';
+    else {
+        const res = await pruneResyncFolder(segments, push.keptAssetIds, false);
+        trashed = res.trashed;
+    }
+    if (pruneSkipped)
+        log(kleur.yellow(`! Nothing moved to Trash (${pruneSkipped}). Re-run once fixed.`));
+    else
+        log(kleur.green(`✓ ${label} resynced. ${trashed} file${trashed === 1 ? '' : 's'} moved to Trash.`));
+    return { push, trashed, pruneSkipped };
+}

package/dist/commands/start.js

@@ -11,6 +11,31 @@ import { initCommand } from './init.js';
 import { loginCommand } from './login.js';
 import { syncCommand } from './sync.js';
 import { cmd } from '../util/invoke.js';
+import { assertKeyValid } from '../util/auth.js';
+import { ApiError } from '../api.js';
+import { connectCommand } from './connect.js';
+import { isAllSpritesGlob } from '../util/engineConnect.js';
+/** Validate a key; only auth rejections map to 'rejected' — other failures throw. */
+export async function checkKey(key, config) {
+    try {
+        await assertKeyValid(key, config);
+        return 'ok';
+    }
+    catch (e) {
+        if (e instanceof ApiError && (e.status === 401 || e.status === 403))
+            return 'rejected';
+        throw e;
+    }
+}
+/** `Sprites/Enemies` → `Sprites/Enemies/**`; already-globbed input is kept. */
+export function folderToGlob(folder) {
+    const f = folder.trim().replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '');
+    return /[*?]/.test(f) ? f : `${f}/**`;
+}
+/** Only ask on an interactive engine project still set to "everything". */
+export function shouldAskFolder(connect, isTTY, engine) {
+    return isTTY && engine && (connect.length === 0 || connect.every(isAllSpritesGlob));
+}
 /**
  * One-command bootstrap for new users. Runs init → key prompt → first sync →
  * prints copy-pasteable watch instructions. Designed so a non-technical user
@@ -55,20 +80,58 @@ export async function startCommand(opts = {}) {
     }
     // 3. Offer to migrate any key sitting in .env / .env.local.
     await maybeMigrateDotenvKey();
-    // 4. Make sure we have a usable key. Env var or stored credentials are fine.
-    const haveEnv = !!process.env.MAGICPIXEL_API_KEY;
+    // 4. Make sure we have a usable key — and that it actually works. A stale
+    //    stored key used to sail through and fail every request with 401.
+    const config = await loadConfig();
+    const envKey = process.env.MAGICPIXEL_API_KEY?.trim();
     const stored = readCredentialsSync();
-    if (!haveEnv && !stored) {
+    if (!envKey && !stored) {
         console.log();
         console.log(kleur.bold('Step: connect your account'));
         await loginCommand();
     }
-    else if (haveEnv) {
+    else if (envKey) {
+        if ((await checkKey(envKey, config)) === 'rejected') {
+            console.log(kleur.red('✖ The MAGICPIXEL_API_KEY in your environment was rejected.'));
+            console.log(kleur.dim('  Fix: set it to a fresh key from https://magicpixel.art/settings (or unset it and re-run).'));
+            process.exitCode = 1;
+            return;
+        }
         console.log(kleur.dim('  Using MAGICPIXEL_API_KEY from your environment.'));
     }
+    else if (stored && (await checkKey(stored.apiKey, config)) === 'rejected') {
+        console.log(kleur.yellow('! Your saved key was rejected (revoked, or from another account).'));
+        if (!stdin.isTTY) {
+            console.log(kleur.dim(`  Fix: run \`${cmd('login')} --key mp_live_…\` with a fresh key from https://magicpixel.art/settings.`));
+            process.exitCode = 1;
+            return;
+        }
+        console.log(kleur.bold('Step: connect your account'));
+        await loginCommand();
+    }
     else {
         console.log(kleur.dim('  Using stored credentials from .magicpixel/credentials.'));
     }
+    // 4b. Don't push a whole game by surprise — offer one folder first.
+    let folder = opts.folder?.trim();
+    if (!folder && shouldAskFolder(config.connect, !!stdin.isTTY, isEngineKind(kind))) {
+        const rl = createInterface({ input: stdin, output: stdout });
+        try {
+            folder = (await rl.question(`${kleur.cyan('?')} Sync all sprites, or one folder? ${kleur.dim('(type a folder like Sprites/Enemies, or press Enter for all)')} `)).trim();
+        }
+        finally {
+            rl.close();
+        }
+    }
+    if (folder) {
+        console.log();
+        console.log(kleur.bold('Step: sync one folder'));
+        await connectCommand(folderToGlob(folder));
+        console.log();
+        console.log(kleur.dim(`  Add another folder later with \`${cmd('connect')} "<folder>/**"\`.`));
+        console.log(`  ${kleur.green('▶')} ${kleur.bold(`${cmd('sync')} --watch`)}   ${kleur.dim('# keeps sprites fresh while you edit them in MagicPixel')}`);
+        return;
+    }
     // 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.

package/dist/commands/sync.js

@@ -3,7 +3,7 @@ import ora from 'ora';
 import { mkdir, unlink, readdir, rm, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { dirname, relative, resolve } from 'node:path';
-import { loadConfig, loadState, saveState } from '../config.js';
+import { loadConfig, loadState, saveState, resetStateIfProjectChanged, PROJECT_CHANGED_MESSAGE } from '../config.js';
 import { ensureEngineConnect } from '../util/engineConnect.js';
 import { fetchManifestSnapshot, fetchAssetBytes, ApiError, DAILY_QUOTA_ERROR_CODE, getLastProjectInfo, primeManifestEtags, manifestEtagsSnapshot } from '../api.js';
 import { fileSha256 } from '../util/hash.js';
@@ -28,6 +28,47 @@ import { canSkipWithoutHashing, decidePull, hasNewExplicitRelease } from '../uti
 import { hasUnpushedLocalEdit } from '../util/localEdit.js';
 import { shouldReconcile } from '../util/reconcile.js';
 import { runPush } from './push.js';
+import { claimResyncRequest, reportResyncRequest } from '../api.js';
+import { runResync } from './resync.js';
+import { keyInScope, pathInScope, resolveSyncScope, scopeFingerprint } from '../util/syncScope.js';
+/** How often the watcher asks for a library "Resync from game" request. */
+const RESYNC_POLL_MS = 15_000;
+let lastResyncPollAt = 0;
+/**
+ * Run one queued library "Resync from game…" request, if any. Never throws:
+ * a failed resync is reported back to MagicPixel and the watcher keeps going.
+ */
+async function maybeRunQueuedResync(quiet) {
+    if (Date.now() - lastResyncPollAt < RESYNC_POLL_MS)
+        return;
+    lastResyncPollAt = Date.now();
+    let req = null;
+    try {
+        req = await claimResyncRequest();
+    }
+    catch {
+        return;
+    }
+    if (!req)
+        return;
+    if (!quiet) {
+        process.stdout.write('\x1b[2K\r');
+        console.log(kleur.bold(`↻ Resyncing "${req.folderName}" from your game (requested in MagicPixel)…`));
+    }
+    try {
+        const out = await runResync(req.folderPath, { yes: true, quiet });
+        const p = out.push;
+        await reportResyncRequest(req.id, 'done', out.pruneSkipped ? `Nothing trashed: ${out.pruneSkipped}` : null, {
+            created: p.created, updated: p.updated, unchanged: p.unchanged,
+            conflict: p.conflict, error: p.error, trashed: out.trashed,
+        });
+    }
+    catch (e) {
+        await reportResyncRequest(req.id, 'failed', e.message).catch(() => { });
+        if (!quiet)
+            console.log(kleur.red(`! Resync failed: ${e.message}`));
+    }
+}
 /** Did the push half of a run actually move bytes into MagicPixel? */
 export function pushWasActive(pushed) {
     if (!pushed)
@@ -82,6 +123,15 @@ async function watchLoop(opts) {
     // 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')}`);
+    try {
+        const scope = resolveSyncScope(opts.only ?? (await loadConfig()).syncOnly);
+        if (scope) {
+            console.log(`   Only:     ${scope.folders.length} folder${scope.folders.length === 1 ? '' : 's'}: ${kleur.cyan(scope.folders.join(', '))}`);
+        }
+    }
+    catch {
+        /* header is cosmetic */
+    }
     let countSpinner = null;
     if (!opts.quiet) {
         try {
@@ -222,6 +272,7 @@ async function watchLoop(opts) {
             pausedForNetwork = false;
             pausedForQuota = false;
             consecutiveAuthFailures = 0;
+            await maybeRunQueuedResync(opts.quiet === true);
             if (wasPausedForAuth && !opts.quiet) {
                 process.stdout.write('\x1b[2K\r');
                 console.log(`${kleur.dim(timestamp())} ${kleur.green('✓')} Key accepted again — resuming.`);
@@ -494,6 +545,12 @@ async function runOnce(opts, runOpts = {}) {
     if (reconcileDue && verbose) {
         console.log(kleur.dim('Running a full reconcile (periodic) to clear anything deleted in MagicPixel.'));
     }
+    // Folder scope: a changed scope needs one full pass so newly-included
+    // folders aren't skipped by a cursor that advanced while they were held.
+    const scope = resolveSyncScope(opts.only ?? config.syncOnly);
+    const scopeKey = scopeFingerprint(scope);
+    if (scopeKey !== state.syncScope)
+        since = undefined;
     const previousAssets = state.assets ?? {}; // id → key from prior sync
     const spinner = verbose
         ? ora(since ? `Fetching manifest since ${humanTime(since)}…` : 'Fetching manifest…').start()
@@ -541,6 +598,12 @@ async function runOnce(opts, runOpts = {}) {
         // user presses Sync (the release bumps `updated_at`).
         observedUpdatedAt = maxIsoTimestamp(snapshot.entries.map((e) => e.updated_at));
         const projectInfo = getLastProjectInfo();
+        // Full read + empty project is the only safe "cloud is empty" signal.
+        if (resetStateIfProjectChanged(state, projectInfo?.id, !since && snapshot.entries.length === 0)) {
+            await saveState(state);
+            if (verbose)
+                console.log(kleur.yellow(`! ${PROJECT_CHANGED_MESSAGE}`));
+        }
         const projectSuffix = projectInfo && verbose
             ? kleur.dim(` · project: ${projectInfo.name ?? projectInfo.id.slice(0, 8)}`)
             : '';
@@ -589,8 +652,39 @@ async function runOnce(opts, runOpts = {}) {
             : { files: [], capped: false });
     if (!runOpts.gameIndex)
         runOpts.onGameIndex?.(gameIndex);
-    const connected = matchConnectGlobs(gameIndex, config.connect ?? []);
+    const fullGameIndex = gameIndex;
+    const scopedGameIndex = scope
+        ? { ...fullGameIndex, files: fullGameIndex.files.filter((f) => pathInScope(scope, f.sourceRel)) }
+        : fullGameIndex;
+    const connected = matchConnectGlobs(scopedGameIndex, config.connect ?? []);
     const sourceByKey = collectSourceRelMap(connected.entries, state.synced);
+    if (scope) {
+        // Out-of-scope rows become hold-only: never pulled, and their folders are
+        // protected from every prune path exactly like unreleased documents.
+        const inScope = [];
+        for (const e of manifest) {
+            const rel = sourceByKey.get(e.key) ?? state.synced?.[e.key]?.sourceRel;
+            if (keyInScope(scope, e.key, rel))
+                inScope.push(e);
+            else
+                withheldEntries.push(e);
+        }
+        manifest = inScope;
+        removedRemoteKeys = removedRemoteKeys.filter((k) => keyInScope(scope, k, sourceByKey.get(k) ?? state.synced?.[k]?.sourceRel));
+        if (scopedGameIndex.files.length === 0 && manifest.length === 0) {
+            const msg = `Nothing found in ${scope.folders.join(', ')}.\n` +
+                `  Fix: check the folder path (relative to ${process.cwd()}, e.g. Runtime/Sprites/Entities/decorations).`;
+            // Watch would hit this on every tick — say it once and stop.
+            if (runOpts.watchMode) {
+                console.error(kleur.red(msg));
+                process.exit(1);
+            }
+            throw new Error(msg);
+        }
+        if (verbose) {
+            console.log(kleur.dim(`  only ${scope.folders.join(', ')} → ${connected.entries.length} game file${connected.entries.length === 1 ? '' : 's'} · ${manifest.length} in MagicPixel`));
+        }
+    }
     aliasCollisionKeys(sourceByKey, manifest.map((e) => e.key));
     if (verbose && gameIndex.capped) {
         console.log(kleur.yellow(`! ${GAME_INDEX_CAP_HINT}`));
@@ -954,6 +1048,8 @@ async function runOnce(opts, runOpts = {}) {
     for (const p of orphanSet) {
         if (conflictPaths.has(p))
             continue;
+        if (scope && !pathInScope(scope, p))
+            continue; // outside --only: hands off
         const key = keyByPath.get(p);
         if (key &&
             (await hasUnpushedLocalEdit({ absPath: p, baselineDiskSha256: synced[key]?.diskSha256 }))) {
@@ -1000,7 +1096,8 @@ async function runOnce(opts, runOpts = {}) {
         if (top)
             knownFolderSlugs.add(top);
     }
-    const legacyFolders = await findLegacySuffixFolders(config.outDir, knownFolderSlugs);
+    const legacyFolders = (await findLegacySuffixFolders(config.outDir, knownFolderSlugs))
+        .filter((lf) => !scope || pathInScope(scope, lf.abs)); // --only: hands off elsewhere
     if (verbose) {
         console.log();
         console.log(kleur.bold('Plan:'));
@@ -1324,6 +1421,7 @@ async function runOnce(opts, runOpts = {}) {
         assets: nextAssets,
         synced: nextSynced,
         manifestEtags: manifestEtagsSnapshot(),
+        syncScope: scopeKey,
         // A completed full pass is the only run that can prove nothing is orphaned.
         ...(!since && result.failed === 0 ? { lastReconcile: startedAt } : {}),
     };
@@ -1396,7 +1494,7 @@ async function runOnce(opts, runOpts = {}) {
         console.log(kleur.yellow(`\n${result.failed} download${result.failed === 1 ? '' : 's'} failed — lastSync not advanced. Re-run to retry.`));
     }
     onStatus?.('Checking your game files…');
-    const pushed = await maybePushLocalSprites(config.push, verbose, gameIndex, live && !!runOpts.watchMode, onStatus, conflictSet);
+    const pushed = await maybePushLocalSprites(config.push, verbose, scopedGameIndex, live && !!runOpts.watchMode, onStatus, conflictSet);
     if (verbose) {
         console.log();
         const summary = `downloaded ${downloaded} (added ${result.added.length}, modified ${result.modified.length}), ` +

package/dist/config.js

@@ -10,6 +10,29 @@ const CONFIG_FILENAME = 'magicpixel.json';
 const STATE_DIR = '.magicpixel';
 const STATE_FILENAME = 'state.json';
 const DEFAULT_ENDPOINT = 'https://sddsilidjhvtvejzvolx.supabase.co/functions/v1/integration-assets';
+/**
+ * The upload record is only valid for the project it was built against. A new
+ * key / account / project must not inherit "already uploaded" entries, or every
+ * sprite is skipped as unchanged and nothing reaches the new project.
+ * Legacy records (no projectId) are treated as stale when the server reports
+ * an empty project. Mutates `state`; returns true when it was reset. Disk is
+ * never touched.
+ */
+export function resetStateIfProjectChanged(state, projectId, cloudIsEmpty) {
+    if (!projectId)
+        return false;
+    const hasRecord = Object.keys(state.synced ?? {}).length > 0 || Object.keys(state.assets ?? {}).length > 0;
+    const stale = state.projectId ? state.projectId !== projectId : hasRecord && cloudIsEmpty;
+    if (stale) {
+        delete state.synced;
+        delete state.assets;
+        delete state.manifestEtags;
+        delete state.lastReconcile;
+    }
+    state.projectId = projectId;
+    return stale;
+}
+export const PROJECT_CHANGED_MESSAGE = 'This key belongs to a different MagicPixel project — re-uploading your connected folders.';
 export const defaultConfig = {
     outDir: 'src/assets/magicpixel',
     include: ['**/*'],
@@ -89,6 +112,7 @@ export async function loadConfig(cwd = process.cwd()) {
         unityPpu,
         push: parsed.push === false ? false : undefined,
         connect,
+        ...(parsed.syncOnly !== undefined ? { syncOnly: normalizeGlobList(parsed.syncOnly, 'syncOnly') } : {}),
     };
 }
 const MAX_GLOBS = 64;

package/dist/index.js

@@ -15,9 +15,11 @@ 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 { resyncCommand } from './commands/resync.js';
 import { searchCommand } from './commands/search.js';
 import { parseWatchInterval, parseConcurrency } from './util/flagValidators.js';
 import { CLI_VERSION } from './version.js';
+import { cmd } from './util/invoke.js';
 // Node version guard
 const major = Number(process.versions.node.split('.')[0]);
 if (major < 18) {
@@ -51,6 +53,7 @@ program
     .command('start')
     .description('One-command first-run setup: init + login + first sync')
     .option('--force', 'Re-run init even if magicpixel.json exists')
+    .option('--folder <path>', 'Sync only this game folder first (skips the "all or one folder" question)')
     .action(wrap("start", async (opts) => startCommand(opts)));
 program
     .command('init')
@@ -90,8 +93,16 @@ program
     .option('-w, --watch [seconds]', 'Poll for changes (default 2s; auto-slows to 5s after ~1min idle, 10s after ~5min)', parseWatchInterval)
     .option('-q, --quiet', 'Minimal output (for CI)')
     .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)));
+    .option('--only <folder...>', 'Only sync these game folders (repeatable), e.g. Runtime/Sprites/Entities/decorations')
+    .argument('[extra...]')
+    .addHelpText('after', '\nExamples:\n  $ magicpixel sync --watch --only Runtime/Sprites/Enemies   # one folder\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 (extra, opts) => {
+    if (extra.length > 0) {
+        throw new Error(`sync doesn't take a folder (got "${extra.join(' ')}").\n` +
+            `  Fix: ${cmd(`sync --only ${extra[0].replace(/^\/+/, '')}`)}`);
+    }
+    return syncCommand(opts);
+}));
 program
     .command('push')
     .description('Upload local sprite edits back to MagicPixel (two-way sync)')
@@ -100,6 +111,13 @@ program
     .option('--force', 'Keep your local copy when a sprite also changed in MagicPixel')
     .addHelpText('after', '\nExamples:\n  $ magicpixel push --dry-run      # see what changed on disk\n  $ magicpixel push                # send local edits + new sprites\n  $ magicpixel push --force        # your local copy wins on both-sides-changed\n')
     .action(wrap("push", async (opts) => pushCommand(opts)));
+program
+    .command('resync <folder>')
+    .description('Make one MagicPixel folder match your local game folder (local wins, missing files go to Trash)')
+    .option('-y, --yes', 'Skip the confirmation question')
+    .option('--dry-run', 'Show what would change without sending anything')
+    .addHelpText('after', '\nExamples:\n  $ magicpixel resync Sprites/Enemies --dry-run\n  $ magicpixel resync Sprites/Enemies\n')
+    .action(wrap("resync", async (folder, opts) => resyncCommand(folder, opts)));
 program
     .command('connect <glob>')
     .description('Limit which game folders sync (default is all sprites)')

package/dist/util/pushPlan.js

@@ -120,11 +120,13 @@ export function planPush(candidates, synced, opts = {}) {
         if (known) {
             const connected = Boolean(c.sourceRel || opts.folderTreeKeys?.has(c.key) || (stateKey != null && opts.folderTreeKeys?.has(stateKey)));
             const lastDisk = lastPushedDiskSha(known, { connected });
-            if (lastDisk === c.diskSha256) {
+            // Resync (replace) sends every in-scope sprite: local wins even when
+            // only the MagicPixel copy changed. The server reports true no-ops.
+            if (lastDisk === c.diskSha256 && !opts.replace) {
                 out.push({ kind: 'skip', key: c.key, reason: 'unchanged' });
                 continue;
             }
-            if (lastDisk === undefined) {
+            if (lastDisk === undefined && !opts.replace) {
                 // Connected original with no disk baseline yet. Ingest's composite
                 // sha is not the game file — seeding happens in `applyDiskFingerprints`.
                 out.push({ kind: 'skip', key: c.key, reason: 'unchanged' });

package/dist/util/syncScope.js

@@ -0,0 +1,44 @@
+/**
+ * `sync --only <folder>`: limit both halves of a sync (push + pull + prune) to
+ * a few game folders. Everything outside the scope is treated as hold-only —
+ * never pulled, pushed, or deleted — so a huge project can be watched one
+ * folder at a time.
+ */
+import { relative } from 'node:path';
+import { keyInFolder, parseFolderArg } from '../commands/resync.js';
+/** Accepts `/Runtime/Foo/`, `Runtime\\Foo`, `Runtime/Foo/**`. */
+export function normalizeScopeFolder(input) {
+    return input
+        .trim()
+        .replace(/\\/g, '/')
+        .replace(/\/\*\*?$/g, '')
+        .replace(/^\.?\/+/, '')
+        .replace(/\/+$/, '')
+        .replace(/\/{2,}/g, '/');
+}
+export function resolveSyncScope(inputs) {
+    const folders = Array.from(new Set((inputs ?? []).map(normalizeScopeFolder).filter(Boolean)));
+    if (folders.length === 0)
+        return null;
+    return {
+        folders: folders.map((f) => f.toLowerCase()),
+        keySegments: folders.map(parseFolderArg).filter((s) => s.length > 0),
+    };
+}
+/** Is a cwd-relative (or absolute) path inside the scope? */
+export function pathInScope(scope, path) {
+    const rel = (path.startsWith('/') || /^[a-z]:/i.test(path) ? relative(process.cwd(), path) : path)
+        .replace(/\\/g, '/')
+        .toLowerCase();
+    return scope.folders.some((f) => rel === f || rel.startsWith(`${f}/`));
+}
+/** A manifest key is in scope when its game file or its library folder is. */
+export function keyInScope(scope, key, sourceRel) {
+    if (sourceRel)
+        return pathInScope(scope, sourceRel);
+    return scope.keySegments.some((segs) => keyInFolder(key, segs));
+}
+/** Stable fingerprint persisted in state — a change forces one full pass. */
+export function scopeFingerprint(scope) {
+    return scope ? [...scope.folders].sort().join('|') : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magicpixelart/cli",
-  "version": "0.5.28",
+  "version": "0.5.31",
   "description": "Sync MagicPixel pixel-art assets to your local project.",
   "type": "module",
   "bin": {