@magicpixelart/cli 0.5.2 → 0.5.4

package/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [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
+
+- **Continuous `.magicpixel/state.json.<pid>.<hex>.tmp` churn in watch mode.**
+  `saveState()` still used `atomicWrite`, and because watch mode persists
+  state every poll, editors like VS Code visibly filled `.magicpixel/` with
+  staged `state.json.*.tmp` files before the rename landed or when file
+  watchers raced the staging path. State saves now use a direct `writeFile`
+  with `0600` permissions instead. This is safe because `state.json` is a
+  recoverable cache: if a process dies mid-write, `loadState()` already
+  quarantines corrupt JSON and the next sync re-derives the snapshot from the
+  manifest and local files. `atomicWrite` remains for durable config,
+  credentials, `AGENTS.md`, package metadata, and generated index files.
+
 ## [0.5.2] — 2026-06-02
 
 ### Fixed

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/sync.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
@@ -427,6 +428,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/config.js

@@ -1,4 +1,4 @@
-import { readFile, mkdir, rename } from 'node:fs/promises';
+import { readFile, mkdir, rename, writeFile, chmod } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { assertSafeOutDir, MAX_GLOB_LEN, validateEndpointUrl } from './util/security.js';
@@ -151,11 +151,19 @@ export async function saveState(state, cwd = process.cwd()) {
     const path = statePath(cwd);
     try {
         await mkdir(dirname(path), { recursive: true });
-        // Atomic write: stage to a sibling tmp file then rename. Prevents a half-
-        // written state.json on crash/power-loss, which would then poison the next
-        // run (and require the corrupt-state recovery path above). Mode 0600
-        // because state.json sits next to the API-key-bearing credentials file.
-        await atomicWrite(path, JSON.stringify(state, null, 2) + '\n', { mode: 0o600 });
+        // state.json is saved on every watch tick, so it must not use a visible
+        // stage-and-rename tmp path (`state.json.<pid>.<hex>.tmp`) that churns in
+        // VS Code / Vite file watchers. A torn state write is recoverable: loadState
+        // quarantines corrupt JSON and the next sync re-derives state from disk +
+        // manifest, so direct writeFile is the safer UX trade-off here. Keep
+        // atomicWrite for durable config/credentials/index writers.
+        await writeFile(path, JSON.stringify(state, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
+        try {
+            await chmod(path, 0o600);
+        }
+        catch {
+            // Windows / read-only FS — ignore. The contents are non-secret sync state.
+        }
     }
     catch (e) {
         throw friendlyFsError(e, {

package/dist/util/atomicWrite.js

@@ -3,13 +3,13 @@ import { tmpPathFor } from './security.js';
 /**
  * Stage-and-rename file write. A crash mid-write can never leave a truncated
  * file on disk — the rename is atomic on every POSIX FS and on NTFS. Used
- * everywhere a corrupted target would break the project (state.json,
- * package.json, magicpixel.json, credentials, AGENTS.md, generated index files,
- * asset PNGs from `sync`).
+ * everywhere a corrupted target would break the project (package.json,
+ * magicpixel.json, credentials, AGENTS.md, generated index files). High-churn
+ * `state.json` saves and asset PNG writes intentionally use direct writeFile;
+ * see CHANGELOG 0.5.2/0.5.3 for the watcher/HMR trade-offs.
  *
- * Accepts `string | Uint8Array` so the asset-bytes writer in `sync` can reuse
- * this instead of duplicating the staging logic (one of the two prior leak
- * sites — see CHANGELOG 0.5.1).
+ * Accepts `string | Uint8Array` for callers that need binary-safe atomic
+ * writes, though asset bytes currently avoid this path for HMR compatibility.
  *
  * CRITICAL: On ANY failure between staging and rename, the tmp file is
  * unlinked before the original error is rethrown. Without this, every rare

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,6 +1,6 @@
 {
   "name": "@magicpixelart/cli",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Sync MagicPixel pixel-art assets to your local project.",
   "type": "module",
   "bin": {