@magicpixelart/cli 0.5.29 → 0.5.32

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.32] - 2026-10-05
+
+### Fixed
+- `sync --watch` status lines are clipped to the terminal width, so a long sprite path no longer wraps and leaves the previous status piled on screen.
+
+## [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]

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` +

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,6 +37,17 @@ 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 = {}) {

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';
@@ -23,13 +23,14 @@ 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 { formatSlowTickLine, formatWatchSpriteLine, SLOW_TICK_HEARTBEAT_MS } from '../util/watchCopy.js';
+import { fitStatusLine, formatSlowTickLine, formatWatchSpriteLine, SLOW_TICK_HEARTBEAT_MS } from '../util/watchCopy.js';
 import { canSkipWithoutHashing, decidePull, hasNewExplicitRelease } from '../util/pullDecision.js';
 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;
@@ -122,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 {
@@ -217,7 +227,7 @@ async function watchLoop(opts) {
         const onStatus = (msg) => {
             if (opts.quiet)
                 return;
-            process.stdout.write(`\r\x1b[2K${kleur.dim(`${timestamp()} ${msg}`)}`);
+            writeStatusLine(msg);
         };
         // Heartbeat: a tick that legitimately takes minutes (huge first pull, slow
         // link) must not look like the silent hang a timeout-less fetch used to
@@ -297,7 +307,7 @@ async function watchLoop(opts) {
                 printChanges(r, /* indent */ '  ');
             }
             else {
-                process.stdout.write(`\r\x1b[2K${kleur.dim(`${timestamp()} Waiting for edits… (${r.unchanged} up to date)`)}`);
+                writeStatusLine(`Waiting for edits… (${r.unchanged} up to date)`);
             }
         }
         catch (e) {
@@ -535,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()
@@ -582,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)}`)
             : '';
@@ -630,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}`));
@@ -995,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 }))) {
@@ -1041,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:'));
@@ -1365,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 } : {}),
     };
@@ -1437,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}), ` +
@@ -1518,6 +1575,11 @@ function progressText(done, total, bytes) {
     const bar = '█'.repeat(filled) + '░'.repeat(barWidth - filled);
     return `${bar}  ${done}/${total}  ${kleur.dim(formatBytes(bytes))}`;
 }
+/** Rewrite the watcher's single status row, clipped so it never wraps. */
+function writeStatusLine(msg) {
+    const line = fitStatusLine(`${timestamp()} ${msg}`, process.stdout.columns);
+    process.stdout.write(`\r\x1b[2K${kleur.dim(line)}`);
+}
 function timestamp() {
     const d = new Date();
     return `[${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}:${String(d.getSeconds()).padStart(2, '0')}]`;

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

@@ -19,6 +19,7 @@ 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) {
@@ -52,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')
@@ -91,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)')

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/dist/util/watchCopy.js

@@ -39,3 +39,19 @@ export function formatSlowTickLine(elapsedSec, lastStatus) {
         ? `${what} — still working (${elapsed})`
         : `Still working (${elapsed})`;
 }
+/**
+ * Fit a carriage-return status line to one terminal row. `\r\x1b[2K` only
+ * clears the row the cursor is on, so a line that wraps leaves its first rows
+ * behind and the next status prints after them (long "Looking through your
+ * game sprites… <folder>" lines piled up this way). No width (not a TTY) →
+ * unchanged.
+ */
+export function fitStatusLine(line, columns) {
+    if (!columns || columns < 2)
+        return line;
+    const max = columns - 1; // leave the last cell free so the cursor can't wrap
+    const chars = Array.from(line);
+    if (chars.length <= max)
+        return line;
+    return `${chars.slice(0, max - 1).join('')}…`;
+}

package/package.json

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