@magicpixelart/cli 0.5.3 → 0.5.5

package/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.5.5] — 2026-07-12
+
+### Added
+
+- **Bound project name in `whoami` / `status` / `sync`.** Manifest responses
+  now expose the API key's project via `x-magicpixel-project-*` headers and an
+  optional `project` body field. The CLI surfaces `project: <name>` so a
+  key-bound-to-the-wrong-project mistake is obvious at a glance. On empty
+  fresh syncs the server may also send `totalInProject` + a ready-to-print
+  `hint`; `whoami`, `status`, and verbose `sync` print it instead of a silent
+  zero. Old servers without the headers keep working — the project line is
+  simply omitted.
+
+## [0.5.4] — 2026-06-22
+
+### Added
+
+- **Game engine project detection.** `init` and `doctor` now recognize Unity
+  (`ProjectSettings/ProjectVersion.txt`), Godot (`project.godot`), and
+  GameMaker (root `*.yyp`) and suggest engine-conventional `outDir` defaults:
+  `Assets/MagicPixel`, `assets/magicpixel`, and `datafiles/magicpixel`.
+  JS framework detection still runs first (monorepo-safe). Engine projects
+  skip typed `index.ts` and npm watch-script prompts; GameMaker prints a
+  one-liner to refresh Included Files after sync. `magicpixel start` remains
+  JS-only and redirects engine users to `init → login → sync --watch`.
+
 ## [0.5.3] — 2026-06-02
 
 ### Fixed

package/dist/api.js

@@ -1,6 +1,21 @@
 import { resolveEndpoint, getApiKey, CLI_VERSION } from './config.js';
 import { etagForSha256, MAX_ASSET_BYTES, readBodyWithLimit, safeFetch, } from './util/security.js';
 import { authHeaders } from './util/authHeaders.js';
+/**
+ * Last-seen project metadata from any manifest response this process made.
+ * Populated as a side-effect of `fetchManifestPage`; read by `whoami`,
+ * `status`, and `sync` to surface `project: <name>` diagnostics.
+ *
+ * Never null after the first successful manifest call. Module-level so the
+ * three commands don't have to thread it through every helper.
+ */
+let lastProjectInfo = null;
+export function getLastProjectInfo() {
+    return lastProjectInfo;
+}
+export function __resetLastProjectInfoForTesting() {
+    lastProjectInfo = null;
+}
 /**
  * Error from the MagicPixel API. `requestId` is the `X-Request-Id` the server
  * echoed (or the one we minted client-side if the server didn't respond) —
@@ -86,6 +101,29 @@ export async function fetchManifestPage(opts) {
             if (!isObject || !Array.isArray(data.items) || !cursorOk) {
                 throw new ApiError(502, withRequestId('manifest: unexpected server response shape (items missing or non-string cursor).', serverRequestId), serverRequestId);
             }
+            // Capture the bound project's name/id from response headers (always
+            // present on 2xx). The body may also carry a richer `project` payload
+            // (empty fresh-sync case, includes totalInProject + hint). Prefer the
+            // body when present so `whoami`/`sync` can print the "0 assets in this
+            // project" nudge without another round-trip.
+            const projectId = res.headers.get('x-magicpixel-project-id');
+            const projectName = res.headers.get('x-magicpixel-project-name');
+            const bodyProject = data.project;
+            if (bodyProject && typeof bodyProject === 'object' && typeof bodyProject.id === 'string') {
+                lastProjectInfo = {
+                    id: bodyProject.id,
+                    name: typeof bodyProject.name === 'string' ? bodyProject.name : (projectName ?? null),
+                    totalInProject: typeof bodyProject.totalInProject === 'number'
+                        ? bodyProject.totalInProject
+                        : undefined,
+                    hint: typeof bodyProject.hint === 'string'
+                        ? bodyProject.hint
+                        : undefined,
+                };
+            }
+            else if (projectId) {
+                lastProjectInfo = { id: projectId, name: projectName };
+            }
             return data;
         }
         const bodyText = await res.text();

package/dist/commands/doctor.js

@@ -4,7 +4,7 @@ import { readFile } from 'node:fs/promises';
 import { resolve, relative } from 'node:path';
 import { loadConfig, loadState, resolveEndpoint, defaultConfig } from '../config.js';
 import { describeKeySource, readKeyForDisplay } from '../util/credentials.js';
-import { detectFramework, hasPackageJson } from '../util/framework.js';
+import { detectProjectKind, hasPackageJson } from '../util/framework.js';
 import { safeFetch } from '../util/security.js';
 import { authHeaders } from '../util/authHeaders.js';
 import { CLI_VERSION } from '../version.js';
@@ -24,7 +24,7 @@ export async function doctorCommand(opts = {}) {
  * state on disk.
  */
 export async function collectDoctorReport(opts = {}) {
-    const framework = await detectFramework();
+    const framework = await detectProjectKind();
     const pkgFound = hasPackageJson();
     let config = null;
     let configErr = null;

package/dist/commands/init.js

@@ -5,7 +5,7 @@ import { resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
 import { configPath, defaultConfig, saveConfig } from '../config.js';
-import { detectFramework, suggestOutDir, hasPackageJson, isStaticOutDir } from '../util/framework.js';
+import { detectProjectKind, suggestOutDir, hasPackageJson, isStaticOutDir, supportsTypedIndex, isEngineKind, } from '../util/framework.js';
 import { assertSafeOutDir } from '../util/security.js';
 import { atomicWrite } from '../util/atomicWrite.js';
 const WATCH_SCRIPT_NAME = 'magicpixel:watch';
@@ -19,18 +19,18 @@ export async function initCommand(opts) {
     const interactive = !opts.yes && stdin.isTTY;
     const config = { ...defaultConfig };
     let addGitignore = true;
-    const framework = await detectFramework();
-    const suggestedOutDir = suggestOutDir(framework);
+    const kind = await detectProjectKind();
+    const suggestedOutDir = suggestOutDir(kind);
     config.outDir = suggestedOutDir;
     const pkgExists = hasPackageJson();
     const pkgPath = resolve(process.cwd(), 'package.json');
-    let addWatchScript = pkgExists;
+    let addWatchScript = pkgExists && !isEngineKind(kind);
     if (interactive) {
         const rl = createInterface({ input: stdin, output: stdout });
         try {
             console.log(kleur.bold('Set up @magicpixelart/cli'));
-            if (framework)
-                console.log(kleur.dim(`  Detected: ${framework}`));
+            if (kind)
+                console.log(kleur.dim(`  Detected: ${kind}`));
             console.log();
             // Re-prompt loop: catch unsafe outDir values (null bytes, `..` segments)
             // at input time rather than letting `loadConfig` reject them on the next
@@ -47,9 +47,11 @@ export async function initCommand(opts) {
                     console.log(kleur.yellow(`  ${e.message} Try again.`));
                 }
             }
-            // Typed index only makes sense when the outDir is importable by a bundler.
-            // public/ and static/ are served as-is and cannot be imported.
-            if (!isStaticOutDir(config.outDir)) {
+            // Typed index only makes sense for JS projects with a bundler-importable outDir.
+            if (!supportsTypedIndex(kind)) {
+                config.emitIndex = false;
+            }
+            else if (!isStaticOutDir(config.outDir)) {
                 const emitAns = (await rl.question(`${kleur.cyan('?')} Emit a typed index.ts for autocomplete? ${kleur.dim('(Y/n)')} `)).trim().toLowerCase();
                 config.emitIndex = emitAns !== 'n' && emitAns !== 'no';
             }
@@ -59,7 +61,7 @@ export async function initCommand(opts) {
             }
             const giAns = (await rl.question(`${kleur.cyan('?')} Add .magicpixel/ to .gitignore? ${kleur.dim('(Y/n)')} `)).trim().toLowerCase();
             addGitignore = giAns !== 'n' && giAns !== 'no';
-            if (pkgExists) {
+            if (pkgExists && !isEngineKind(kind)) {
                 const wAns = (await rl.question(`${kleur.cyan('?')} Add a "${WATCH_SCRIPT_NAME}" script to package.json? ${kleur.dim('(Y/n)')} `)).trim().toLowerCase();
                 addWatchScript = wAns !== 'n' && wAns !== 'no';
             }
@@ -69,11 +71,14 @@ export async function initCommand(opts) {
         }
     }
     else {
-        config.emitIndex = !isStaticOutDir(config.outDir);
+        config.emitIndex = supportsTypedIndex(kind) && !isStaticOutDir(config.outDir);
     }
     await saveConfig(config);
     console.log();
     console.log(kleur.green('✓ wrote magicpixel.json'));
+    if (kind === 'GameMaker') {
+        console.log(kleur.dim("  Note: GameMaker doesn't auto-import — refresh Included Files after each sync."));
+    }
     if (addGitignore) {
         const added = await ensureGitignore();
         if (added)

package/dist/commands/start.js

@@ -5,7 +5,7 @@ import { createInterface } from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
 import { resolve } from 'node:path';
 import { configPath, loadConfig } from '../config.js';
-import { hasPackageJson } from '../util/framework.js';
+import { detectProjectKind, hasPackageJson, isEngineKind } from '../util/framework.js';
 import { findKeyInDotenv, readCredentialsSync, writeCredentials } from '../util/credentials.js';
 import { initCommand } from './init.js';
 import { loginCommand } from './login.js';
@@ -20,8 +20,14 @@ 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();
-    // 1. Need a package.json — refuse to scaffold into a non-project directory.
+    // 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}. \`magicpixel start\` is JS-only; run ` +
+                '`npx magicpixel init && npx magicpixel login && npx magicpixel sync --watch` instead.'));
+            return;
+        }
         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;

package/dist/commands/status.js

@@ -1,6 +1,6 @@
 import kleur from 'kleur';
 import { loadConfig, loadState, resolveEndpoint } from '../config.js';
-import { fetchAllManifest } from '../api.js';
+import { fetchAllManifest, getLastProjectInfo } from '../api.js';
 import { fileSha256 } from '../util/hash.js';
 import { assetDiskPath } from '../util/paths.js';
 import { readKeyForDisplay } from '../util/credentials.js';
@@ -66,10 +66,18 @@ export async function statusCommand() {
             else
                 changed++;
         })));
-        console.log(`  remote assets: ${manifest.length}`);
+        const project = getLastProjectInfo();
+        const projectSuffix = project ? kleur.dim(` (project: ${project.name ?? project.id.slice(0, 8)})`) : '';
+        console.log(`  remote assets: ${manifest.length}${projectSuffix}`);
         console.log(`  ${kleur.dim('=')} unchanged: ${unchanged}`);
         console.log(`  ${kleur.yellow('~')} changed:   ${changed}`);
         console.log(`  ${kleur.green('+')} missing:   ${missing}`);
+        if (manifest.length === 0 && project?.hint) {
+            // Fresh sync into an empty-project key — surface the server's hint so
+            // a project mismatch is one glance away instead of a silent zero.
+            console.log();
+            console.log(kleur.yellow(`  ${project.hint}`));
+        }
     }
     catch (e) {
         console.log(kleur.red(`  manifest fetch failed: ${e.message.split('\n')[0]}`));

package/dist/commands/sync.js

@@ -5,7 +5,7 @@ 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 { fetchAllManifest, fetchAssetBytes, ApiError } from '../api.js';
+import { fetchAllManifest, fetchAssetBytes, ApiError, getLastProjectInfo } from '../api.js';
 import { fileSha256 } from '../util/hash.js';
 import { assetDiskPath, assetDiskPathFromKey, pruneEmptyDirs, walkOutDirPngs } from '../util/paths.js';
 import { createLimit } from '../util/limit.js';
@@ -15,6 +15,7 @@ import { runTmpJanitor } from '../util/tmpJanitor.js';
 import { friendlyFsError } from '../util/errors.js';
 import { maxIsoTimestamp } from '../util/iso.js';
 import { formatBytes } from '../util/format.js';
+import { computePreviousKeyOrphans } from '../util/previousKeyOrphans.js';
 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
@@ -318,7 +319,19 @@ async function runOnce(opts, runOpts = {}) {
     let manifest;
     try {
         manifest = await fetchAllManifest(config, since);
-        spinner?.succeed(`Manifest: ${manifest.length} asset${manifest.length === 1 ? '' : 's'}${since ? kleur.dim(' (incremental)') : ''}`);
+        const projectInfo = getLastProjectInfo();
+        const projectSuffix = projectInfo && verbose
+            ? kleur.dim(` · project: ${projectInfo.name ?? projectInfo.id.slice(0, 8)}`)
+            : '';
+        spinner?.succeed(`Manifest: ${manifest.length} asset${manifest.length === 1 ? '' : 's'}${since ? kleur.dim(' (incremental)') : ''}${projectSuffix}`);
+        // Fresh full sync + zero assets = almost always a project-scope mismatch
+        // (the exact case the "0 assets" support flow hits). Server includes a
+        // ready-to-print hint on the empty-fresh-sync response; surface it once
+        // so the user isn't left wondering why sync "did nothing".
+        if (!since && manifest.length === 0 && projectInfo?.hint && verbose) {
+            console.log();
+            console.log(kleur.yellow(`! ${projectInfo.hint}`));
+        }
     }
     catch (e) {
         spinner?.fail('Manifest fetch failed');
@@ -427,6 +440,25 @@ async function runOnce(opts, runOpts = {}) {
     const orphanSet = new Set(orphans);
     for (const p of renameStalePaths)
         orphanSet.add(p);
+    // Server-side rename history. Each manifest entry carries the composite
+    // keys this row was previously emitted under (populated by the editor when
+    // a doc/artboard is renamed). For each prior key whose file is still on
+    // disk and is NOT shadowed by a live manifest entry, we add a rename hint
+    // + prune target — so cruft like `untitled-19/untitled.png` evaporates on
+    // the next sync without the user having to clean it up manually.
+    const prevKeyResult = computePreviousKeyOrphans({
+        manifest,
+        remoteDiskPaths,
+        resolveDiskPath: (key) => assetDiskPathFromKey(config.outDir, key),
+        fileExists: existsSync,
+    });
+    for (const p of prevKeyResult.orphanPaths)
+        orphanSet.add(p);
+    for (const r of prevKeyResult.renames) {
+        if (!renamed.some((x) => x.id === r.id && x.oldKey === r.oldKey)) {
+            renamed.push(r);
+        }
+    }
     orphans = [...orphanSet];
     // Legacy-suffix folder sweep — always runs, even in incremental mode.
     //

package/dist/commands/whoami.js

@@ -1,6 +1,6 @@
 import kleur from 'kleur';
 import { loadConfig, defaultConfig, resolveEndpoint, getApiKey } from '../config.js';
-import { ApiError, retryTransient, retryAfterMsFromResponse } from '../api.js';
+import { ApiError, retryTransient, retryAfterMsFromResponse, getLastProjectInfo } from '../api.js';
 import { safeFetch } from '../util/security.js';
 import { authHeaders } from '../util/authHeaders.js';
 export async function whoamiCommand() {
@@ -49,7 +49,25 @@ export async function whoamiCommand() {
             items: Array.isArray(raw.items) ? raw.items.filter((i) => !!i && typeof i.key === 'string') : [],
             nextCursor: typeof raw.nextCursor === 'string' && raw.nextCursor ? raw.nextCursor : null,
         };
-        return { kind: 'ok', body, serverRequestId };
+        // Prefer body.project (has totalInProject + hint on empty fresh syncs);
+        // fall back to response headers so paginated / non-empty responses still
+        // surface the bound project name. Kept in sync with fetchManifestPage.
+        const bodyProject = raw.project;
+        const projectId = res.headers.get('x-magicpixel-project-id');
+        const projectName = res.headers.get('x-magicpixel-project-name');
+        let project = null;
+        if (bodyProject && typeof bodyProject === 'object' && typeof bodyProject.id === 'string') {
+            project = {
+                id: bodyProject.id,
+                name: typeof bodyProject.name === 'string' ? bodyProject.name : (projectName ?? null),
+                totalInProject: typeof bodyProject.totalInProject === 'number' ? bodyProject.totalInProject : undefined,
+                hint: typeof bodyProject.hint === 'string' ? bodyProject.hint : undefined,
+            };
+        }
+        else if (projectId) {
+            project = { id: projectId, name: projectName };
+        }
+        return { kind: 'ok', body, project, serverRequestId };
     });
     if (result.kind === 'rejected') {
         console.log(kleur.red(`✗ API key rejected (${result.status}).`));
@@ -64,15 +82,33 @@ export async function whoamiCommand() {
         process.exitCode = 1;
         return;
     }
-    const { body } = result;
+    const { body, project } = result;
     const more = body.nextCursor ? '+' : '';
     console.log(kleur.green('✓ key valid'));
     console.log(`  endpoint: ${resolveEndpoint(config)}`);
+    if (project) {
+        const label = project.name ?? '(unnamed)';
+        console.log(`  project:  ${label} ${kleur.dim(`(${project.id.slice(0, 8)}…)`)}`);
+    }
     if (body.count === 0) {
-        console.log(`  visible:  ${kleur.yellow('0 assets — is the key bound to a project with content?')}`);
+        if (project?.hint) {
+            // Server-provided hint already names the project; use it verbatim.
+            console.log(`  visible:  ${kleur.yellow('0 assets')}`);
+            console.log(kleur.dim(`  ${project.hint}`));
+        }
+        else if (project) {
+            console.log(`  visible:  ${kleur.yellow(`0 assets in project "${project.name ?? project.id.slice(0, 8)}"`)}`);
+            console.log(kleur.dim(`  If your art lives in another project, create a key from that project's row in Settings → Projects & API Keys.`));
+        }
+        else {
+            console.log(`  visible:  ${kleur.yellow('0 assets — is the key bound to a project with content?')}`);
+        }
     }
     else {
         console.log(`  visible:  ${body.count}${more} asset${body.count === 1 && !more ? '' : 's'}` +
             ` (first: ${body.items[0]?.key ?? '-'})`);
     }
+    // Reference the module-singleton to avoid an unused-import lint on the
+    // getLastProjectInfo helper (whoami reads project data inline).
+    void getLastProjectInfo;
 }

package/dist/util/framework.js

@@ -1,8 +1,15 @@
-import { existsSync } from 'node:fs';
+import { existsSync, readdirSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
-/** Read `package.json` and infer the framework from its dependencies. */
-export async function detectFramework(cwd = process.cwd()) {
+const ENGINE_KINDS = new Set(['Unity', 'Godot', 'GameMaker']);
+export function isEngineKind(kind) {
+    return kind !== null && ENGINE_KINDS.has(kind);
+}
+/** Typed `index.ts` is JS-only — game engines load PNGs directly. */
+export function supportsTypedIndex(kind) {
+    return !isEngineKind(kind);
+}
+async function detectJsKind(cwd) {
     try {
         const pkgPath = resolve(cwd, 'package.json');
         if (!existsSync(pkgPath))
@@ -31,9 +38,35 @@ export async function detectFramework(cwd = process.cwd()) {
         return null;
     }
 }
-/** Default `outDir` for a detected framework. */
-export function suggestOutDir(framework, cwd = process.cwd()) {
-    switch (framework) {
+function detectEngineKind(cwd) {
+    if (existsSync(resolve(cwd, 'project.godot')))
+        return 'Godot';
+    if (existsSync(resolve(cwd, 'ProjectSettings', 'ProjectVersion.txt')))
+        return 'Unity';
+    try {
+        const yyp = readdirSync(cwd).find((name) => name.endsWith('.yyp'));
+        if (yyp)
+            return 'GameMaker';
+    }
+    catch {
+        // unreadable cwd — treat as no engine marker
+    }
+    return null;
+}
+/** Infer project kind from package.json deps, then engine marker files. */
+export async function detectProjectKind(cwd = process.cwd()) {
+    const js = await detectJsKind(cwd);
+    if (js)
+        return js;
+    return detectEngineKind(cwd);
+}
+/** @deprecated use `detectProjectKind` */
+export async function detectFramework(cwd = process.cwd()) {
+    return detectProjectKind(cwd);
+}
+/** Default `outDir` for a detected project kind. */
+export function suggestOutDir(kind, cwd = process.cwd()) {
+    switch (kind) {
         case 'Next.js':
         case 'Astro':
         case 'Nuxt':
@@ -45,8 +78,14 @@ export function suggestOutDir(framework, cwd = process.cwd()) {
         case 'Remix':
         case 'TanStack Start':
             return 'src/assets/magicpixel';
+        case 'Unity':
+            return 'Assets/MagicPixel';
+        case 'Godot':
+            return 'assets/magicpixel';
+        case 'GameMaker':
+            return 'datafiles/magicpixel';
         default:
-            // No framework detected — prefer src/ if present so the typed index is
+            // No kind detected — prefer src/ if present so the typed index is
             // importable; otherwise fall back to a top-level assets/ dir.
             return existsSync(resolve(cwd, 'src')) ? 'src/assets/magicpixel' : 'assets/magicpixel';
     }

package/dist/util/previousKeyOrphans.js

@@ -0,0 +1,41 @@
+/**
+ * Walk each manifest entry's `previous_keys`, emit orphan paths + rename
+ * hints for prior composite keys whose PNGs still exist on disk and are
+ * NOT shadowed by a live manifest entry.
+ *
+ * Pure / side-effect-free — file existence + path resolution are injected
+ * so this is unit-testable without touching the real filesystem.
+ *
+ * The same `previous_keys` array is repeated on every entry from a given
+ * row; the `(id|prevKey)` signature set keeps the work idempotent.
+ */
+export function computePreviousKeyOrphans(input) {
+    const { manifest, remoteDiskPaths, resolveDiskPath, fileExists } = input;
+    const orphans = new Set();
+    const renames = [];
+    const seen = new Set();
+    for (const entry of manifest) {
+        if (!entry.previous_keys || entry.previous_keys.length === 0)
+            continue;
+        for (const prevKey of entry.previous_keys) {
+            if (prevKey === entry.key)
+                continue;
+            const sig = `${entry.id}|${prevKey}`;
+            if (seen.has(sig))
+                continue;
+            seen.add(sig);
+            const prevPath = resolveDiskPath(prevKey);
+            // Skip when another live entry owns the old path (e.g. the "old" name
+            // is still actively used by a different row in the same project).
+            if (remoteDiskPaths.has(prevPath))
+                continue;
+            if (!fileExists(prevPath))
+                continue;
+            orphans.add(prevPath);
+            if (!renames.some((r) => r.id === entry.id && r.oldKey === prevKey)) {
+                renames.push({ id: entry.id, oldKey: prevKey, newKey: entry.key });
+            }
+        }
+    }
+    return { orphanPaths: [...orphans], renames };
+}

package/package.json

@@ -1,17 +1,12 @@
 {
   "name": "@magicpixelart/cli",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "Sync MagicPixel pixel-art assets to your local project.",
   "type": "module",
   "bin": {
     "magicpixel": "dist/index.js"
   },
-  "files": [
-    "dist",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
+  "files": ["dist", "README.md", "CHANGELOG.md", "LICENSE"],
   "scripts": {
     "build": "tsc && chmod +x dist/index.js",
     "dev": "tsx src/index.ts",