@magicpixelart/cli 0.5.7 → 0.5.8

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.5.8] — 2026-08-26
+
+### Added
+
+- **Connect imports game sprites.** `sync` (and `sync --watch`) now runs `push`
+  automatically so connecting a game project imports existing sprites into the
+  MagicPixel library, flagged Sync to Unity so they appear under Connected.
+  `"push": false` in `magicpixel.json` opts out.
+- **First-connect import.** On Unity/Godot/GameMaker, PNGs under `Assets/` /
+  `assets/` / `datafiles/` are copied into `outDir` if they aren't there yet
+  (skipping Library/Temp/Packages, never overwriting) and then adopted.
+  Root-level PNGs (`hero.png`) adopt as a single-artboard document instead of
+  being skipped.
+
 ## [0.5.7] — 2026-08-26
 
 ### Added

package/README.md

@@ -138,6 +138,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`. |
 | `unitySyncAll` | `boolean?` | `false`             | Unity only: sync every artboard, not just those flagged in the editor. |
+| `push`     | `boolean?` | `true`                  | Upload local PNG changes to MagicPixel on every `sync`. Set `false` for pull-only. |
 | `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/commands/push.js

@@ -22,11 +22,30 @@ import { fileSha256 } from '../util/hash.js';
 import { assetDiskPathFromKey, walkOutDirPngs } from '../util/paths.js';
 import { planPush } from '../util/pushPlan.js';
 import { cmd } from '../util/invoke.js';
-export async function pushCommand(opts) {
+import { detectProjectKind } from '../util/framework.js';
+import { importNearbyGamePngs } from '../util/gameScan.js';
+export async function pushCommand(opts = {}) {
+    await runPush(opts);
+}
+/**
+ * Scan local PNGs and upload new/changed ones into the MagicPixel library.
+ * Used by `magicpixel push` and by `sync` (so connect/watch imports game
+ * sprites without a second command).
+ */
+export async function runPush(opts = {}) {
     const config = await loadConfig();
     const state = await loadState();
-    const spinner = ora('Scanning local sprites…').start();
+    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 };
+    const spinner = quiet ? null : ora('Scanning local sprites…').start();
+    const kind = await detectProjectKind();
+    const scan = await importNearbyGamePngs(config.outDir, kind);
+    const imported = scan.copied;
     const disk = await walkOutDirPngs(config.outDir);
+    const absByKey = new Map(disk.map((a) => [a.key, a.abs]));
     const candidates = [];
     for (const asset of disk) {
         const sha = await fileSha256(asset.abs);
@@ -43,13 +62,14 @@ export async function pushCommand(opts) {
     const legacy = actions.filter((a) => a.kind === 'skip' && a.reason === 'legacy');
     const flattenBlocked = actions.filter((a) => a.kind === 'needs-flatten');
     const sendable = actions.filter((a) => a.kind === 'update' || a.kind === 'adopt');
-    spinner.succeed(`Local sprites: ${candidates.length} · to push ${sendable.length} · unchanged ${skipped}`);
-    if (legacy.length > 0) {
+    spinner?.succeed(`Local sprites: ${candidates.length} · to push ${sendable.length} · unchanged ${skipped}` +
+        (imported ? ` · imported ${imported}` : ''));
+    if (legacy.length > 0 && !quiet) {
         console.log();
         console.log(kleur.yellow(`! ${legacy.length} sprite${legacy.length === 1 ? '' : 's'} came from a legacy single-image file — skipped.`));
         console.log(kleur.dim(`  Fix: open the file in MagicPixel and save it once, then re-run \`${cmd('sync')}\`.`));
     }
-    if (flattenBlocked.length > 0) {
+    if (flattenBlocked.length > 0 && !quiet) {
         console.log();
         console.log(kleur.yellow(`! ${flattenBlocked.length} sprite${flattenBlocked.length === 1 ? '' : 's'} would flatten a multi-layer artboard — skipped.`));
         for (const a of flattenBlocked.slice(0, 10)) {
@@ -58,23 +78,28 @@ export async function pushCommand(opts) {
         console.log(kleur.dim('  Fix: re-run with --flatten to replace them with the flat disk image.'));
     }
     if (sendable.length === 0) {
-        console.log(kleur.green('✓ nothing to push.'));
-        return;
+        if (!quiet)
+            console.log(kleur.green('✓ nothing to push.'));
+        return { ...empty, imported, unchanged: skipped };
     }
     if (opts.dryRun) {
-        console.log();
-        for (const a of sendable) {
-            const verb = a.kind === 'update' ? kleur.yellow('~') : kleur.green('+');
-            console.log(`  ${verb} ${a.key}${a.kind === 'adopt' ? kleur.dim(' (new)') : ''}`);
+        if (!quiet) {
+            console.log();
+            for (const a of sendable) {
+                const verb = a.kind === 'update' ? kleur.yellow('~') : kleur.green('+');
+                console.log(`  ${verb} ${a.key}${a.kind === 'adopt' ? kleur.dim(' (new)') : ''}`);
+            }
+            console.log(kleur.dim('--dry-run: nothing sent.'));
         }
-        console.log(kleur.dim('--dry-run: nothing sent.'));
-        return;
+        return { ...empty, imported };
     }
     const outRoot = resolve(process.cwd(), config.outDir);
     const shaByKey = new Map(candidates.map((c) => [c.key, c.diskSha256]));
     const sprites = [];
     for (const a of sendable) {
-        const abs = resolve(outRoot, `${a.key}.png`);
+        const abs = absByKey.get(a.key);
+        if (!abs)
+            continue;
         const pngBase64 = (await readFile(abs)).toString('base64');
         const diskSha256 = shaByKey.get(a.key);
         if (a.kind === 'update') {
@@ -92,28 +117,23 @@ export async function pushCommand(opts) {
             sprites.push({ key: a.key, pngBase64, diskSha256, path: a.path, pathNames: a.pathNames, name: a.name });
         }
     }
-    const progress = ora(`Pushing 0/${sprites.length}…`).start();
+    const progress = quiet ? null : ora(`Pushing 0/${sprites.length}…`).start();
     const results = [];
     for (let i = 0; i < sprites.length; i += PUSH_BATCH_SIZE) {
         const batch = sprites.slice(i, i + PUSH_BATCH_SIZE);
         const batchResults = await pushSprites(batch);
         results.push(...batchResults);
-        progress.text = `Pushing ${Math.min(i + batch.length, sprites.length)}/${sprites.length}…`;
+        if (progress)
+            progress.text = `Pushing ${Math.min(i + batch.length, sprites.length)}/${sprites.length}…`;
     }
     const counts = { created: 0, updated: 0, unchanged: 0, conflict: 0, error: 0 };
     const nextSynced = { ...(state.synced ?? {}) };
     for (const r of results) {
         counts[r.status] = (counts[r.status] ?? 0) + 1;
-        // The server may have stored the document under a different slug than the
-        // disk folder (collision suffix, slugified name). Move the local files to
-        // the key the manifest will report, or the next `sync` downloads a second
-        // copy alongside this one.
         const stateKey = r.cloudKey && r.cloudKey !== r.key ? r.cloudKey : r.key;
         if (stateKey !== r.key && (r.status === 'created' || r.status === 'updated')) {
             await renameLocalSprite(config.outDir, r.key, stateKey);
         }
-        // Store the sha the cloud now reports so the next `push` is a no-op and
-        // the next `sync` doesn't see a phantom change.
         if ((r.status === 'created' || r.status === 'updated' || r.status === 'unchanged') && r.assetId && r.sha256) {
             if (stateKey !== r.key)
                 delete nextSynced[r.key];
@@ -121,7 +141,6 @@ export async function pushCommand(opts) {
                 assetId: r.assetId,
                 layerIdx: typeof r.layerIdx === 'number' ? r.layerIdx : (nextSynced[stateKey]?.layerIdx ?? 0),
                 sha256: r.sha256,
-                // A push always leaves the artboard single-layer (the flat disk image).
                 layers: 1,
             };
         }
@@ -131,24 +150,29 @@ export async function pushCommand(opts) {
     const summary = `created ${counts.created}, updated ${counts.updated}, unchanged ${counts.unchanged}` +
         (counts.conflict ? `, conflicts ${counts.conflict}` : '') +
         (counts.error ? `, errors ${counts.error}` : '');
-    if (failed)
-        progress.warn(`Push finished with issues. ${summary}`);
-    else
-        progress.succeed(`Pushed. ${summary}`);
-    for (const r of results) {
-        if (r.status === 'conflict') {
-            console.log(`  ${kleur.yellow('!')} ${r.key}: ${conflictHint(r.reason)}`);
+    if (progress) {
+        if (failed)
+            progress.warn(`Push finished with issues. ${summary}`);
+        else
+            progress.succeed(`Pushed. ${summary}`);
+    }
+    if (!quiet) {
+        for (const r of results) {
+            if (r.status === 'conflict') {
+                console.log(`  ${kleur.yellow('!')} ${r.key}: ${conflictHint(r.reason)}`);
+            }
+            else if (r.status === 'error') {
+                console.log(`  ${kleur.red('!')} ${r.key}: ${r.message ?? 'push failed'}`);
+            }
         }
-        else if (r.status === 'error') {
-            console.log(`  ${kleur.red('!')} ${r.key}: ${r.message ?? 'push failed'}`);
+        if (counts.created > 0) {
+            console.log(kleur.dim(`  ${counts.created} new sprite${counts.created === 1 ? '' : 's'} now live in your MagicPixel library ` +
+                `(folders mirrored from ${relative(process.cwd(), outRoot)}). Refresh the library to see them.`));
         }
     }
-    if (counts.created > 0) {
-        console.log(kleur.dim(`  ${counts.created} new sprite${counts.created === 1 ? '' : 's'} now live in your MagicPixel library ` +
-            `(folders mirrored from ${relative(process.cwd(), outRoot)}).`));
-    }
     if (failed)
         process.exitCode = 1;
+    return { ...counts, imported };
 }
 function conflictHint(reason) {
     switch (reason) {

package/dist/commands/start.js

@@ -14,21 +14,16 @@ import { cmd } from '../util/invoke.js';
 /**
  * One-command bootstrap for new users. Runs init → key prompt → first sync →
  * prints copy-pasteable watch instructions. Designed so a non-technical user
- * can paste `npx @magicpixelart/cli start` and end up with sprites on disk and a watch
- * script ready to run.
+ * can paste `npx @magicpixelart/cli start` and end up with game sprites in
+ * MagicPixel (and flagged sprites back on disk) plus a watch script.
  */
 export async function startCommand(opts = {}) {
     console.log(kleur.bold('🪄  MagicPixel — first-run setup'));
-    console.log(kleur.dim('  This walks you through getting your sprites onto disk.'));
+    console.log(kleur.dim('  This connects your game project so existing sprites show up in MagicPixel.'));
     console.log();
-    // 1. `start` is JS-only — engine projects use init + login + sync --watch.
-    if (!hasPackageJson()) {
-        const kind = await detectProjectKind();
-        if (isEngineKind(kind)) {
-            console.log(kleur.yellow(`  Detected ${kind}. \`${cmd('start')}\` is JS-only; run ` +
-                `\`${cmd('init')} && ${cmd('login')} && ${cmd('sync')} --watch\` instead.`));
-            return;
-        }
+    const kind = await detectProjectKind();
+    // Engine projects have no package.json requirement. JS projects still need one.
+    if (!hasPackageJson() && !isEngineKind(kind)) {
         console.log(kleur.yellow('  MagicPixel needs a JavaScript project (package.json) to sync into.\n' +
             '  Run this inside your project folder — the one with package.json.'));
         return;
@@ -74,7 +69,7 @@ export async function startCommand(opts = {}) {
     //    failures without throwing — snapshot around the call so we don't
     //    print a misleading green "you're set up" over a half-failed run.
     console.log();
-    console.log(kleur.bold('Step: first sync'));
+    console.log(kleur.bold('Step: import + sync'));
     const exitBefore = process.exitCode ?? 0;
     await syncCommand({ full: true });
     const firstSyncFailed = (process.exitCode ?? 0) > exitBefore;

package/dist/commands/sync.js

@@ -21,6 +21,7 @@ import { maxIsoTimestamp } from '../util/iso.js';
 import { formatBytes } from '../util/format.js';
 import { computePreviousKeyOrphans } from '../util/previousKeyOrphans.js';
 import { cmd } from '../util/invoke.js';
+import { runPush } from './push.js';
 export async function syncCommand(opts) {
     // Sweep any leaked `<file>.<pid>.<hex>.tmp` files left behind by a prior
     // crashed/killed CLI run before they pile up. Runs once per CLI invocation
@@ -373,16 +374,15 @@ async function runOnce(opts, runOpts = {}) {
                 deselectedPaths.push(p);
         }
         if (filtered.noneFlagged) {
-            // Every artboard is explicitly opted out. Pruning here would delete the
-            // user's whole sprite folder off the back of an unchecked box, so bail
-            // out with a hint instead.
+            // Nothing flagged for pull — don't dump the library, and don't prune.
+            // Local sprites still go up so they appear in MagicPixel on connect.
             if (verbose) {
                 console.log();
-                console.log(kleur.yellow('! No artboards are flagged "Sync to Unity" — nothing to sync.'));
-                console.log(kleur.dim('  Fix: right-click an artboard in MagicPixel → "Sync to Unity",'));
-                console.log(kleur.dim('  or set "unitySyncAll": true in magicpixel.json to sync everything.'));
+                console.log(kleur.yellow('! No artboards are flagged "Sync to Unity" — nothing to pull.'));
+                console.log(kleur.dim('  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.'));
             }
-            return {
+            const empty = {
                 added: [],
                 modified: [],
                 removed: [],
@@ -392,6 +392,8 @@ async function runOnce(opts, runOpts = {}) {
                 bytesSaved: 0,
                 renamed: [],
             };
+            await maybePushLocalSprites(config.push, verbose);
+            return empty;
         }
         const skipped = manifest.length - filtered.entries.length;
         manifest = filtered.entries;
@@ -448,8 +450,7 @@ async function runOnce(opts, runOpts = {}) {
     // delete files outside what the current manifest delta touches).
     const localPngs = await walkOutDirPngs(config.outDir);
     // Sprites created in Unity (or any PNG we never pulled) are pending a
-    // `magicpixel push`, not orphans — see prunePolicy.ts.
-    let pendingPush = [];
+    // push into MagicPixel, not orphans — see prunePolicy.ts.
     if (!since) {
         const trackedPaths = new Set(Object.keys(state.synced ?? {})
             .concat(Object.values(previousAssets))
@@ -469,7 +470,6 @@ async function runOnce(opts, runOpts = {}) {
             isTracked: (p) => trackedPaths.has(p),
         });
         orphans = policy.orphans;
-        pendingPush = policy.pendingPush;
     }
     // Heuristic-rename fallback for incremental mode.
     //
@@ -917,16 +917,26 @@ async function runOnce(opts, runOpts = {}) {
         printChanges(result, '  ', { includeRenames: renamed.length === 0 });
         if (renamed.length > 0)
             printRenames(renamed, { withHints: true });
-        if (pendingPush.length > 0) {
-            console.log();
-            console.log(kleur.yellow(`! ${pendingPush.length} local sprite${pendingPush.length === 1 ? '' : 's'} ${pendingPush.length === 1 ? 'is' : 'are'} not in MagicPixel yet — kept on disk.`));
-            console.log(kleur.dim(`  Fix: run \`${cmd('push')}\` to add them to your library.`));
-        }
     }
+    await maybePushLocalSprites(config.push, verbose);
     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

@@ -86,6 +86,7 @@ export async function loadConfig(cwd = process.cwd()) {
         emitIndex,
         unityPpu,
         unitySyncAll: parsed.unitySyncAll === true ? true : undefined,
+        push: parsed.push === false ? false : undefined,
     };
 }
 const MAX_GLOBS = 64;

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/pushPlan.js

@@ -55,9 +55,15 @@ export function planPush(candidates, synced, opts = {}) {
             });
             continue;
         }
-        // New on disk → adopt. Needs at least a document + artboard segment.
-        const pathNames = c.segments.slice(-MAX_PUSH_PATH_SEGMENTS);
-        const path = pathNames.map(pushSlug);
+        // 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;

package/package.json

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