@magicpixelart/cli 0.5.0 → 0.5.3

package/CHANGELOG.md

@@ -7,6 +7,79 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [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
+
+- **Instant HMR for synced assets (regression from 0.5.1).** 0.5.1 routed
+  the per-asset PNG writer through `atomicWrite`, which stages a
+  `<name>.<pid>.<hex>.tmp` file and `rename()`s over the target. Vite's
+  chokidar watcher only collapses the resulting unlink/add pair when the
+  tmp filename starts with `.` or ends with `~` — ours matches neither, so
+  the target was observed as an `add` rather than a `change` and Vite did
+  not re-push the new image URL to the open browser. Users had to hard
+  refresh to see freshly-synced assets (e.g. after renaming an artboard).
+  The asset writer is back to a direct `writeFile(diskPath, bytes)` —
+  same inode, single `change` event, immediate HMR. Atomicity is not
+  needed for asset bytes (a torn write is self-healing on the next watch
+  tick via sha mismatch); `atomicWrite` remains in use for `state.json`,
+  credentials, `AGENTS.md`, `package.json`, and `magicpixel.json`, where
+  torn writes WOULD corrupt cross-run state. A regression-guard test
+  (`tests/sync.assetWriterDirect.test.ts`) pins this contract.
+
+## [0.5.1] — 2026-06-02
+
+### Fixed
+
+- **`.tmp` file leak in `atomicWrite` and the asset writer.** Every CLI write
+  that goes through `atomicWrite` (`state.json`, `package.json`,
+  `magicpixel.json`, credentials, `AGENTS.md`, the generated index) and the
+  inline tmp+rename in `sync` previously skipped cleanup when `rename()`
+  threw (FS hiccup, AV scan, racing writer, ENOSPC). Because `saveState`
+  fires every watch tick, even a low failure rate accumulated hundreds of
+  `<file>.<pid>.<hex>.tmp` files inside `.magicpixel/` and
+  `src/assets/magicpixel/<folder>/` — and they were invisible to the
+  `*.png`-only orphan walker. `atomicWrite` now wraps the write/chmod/rename
+  body in a `try { … } catch { unlink(tmp); throw }` block; the asset writer
+  in `sync` is reduced to a single `atomicWrite(diskPath, bytes)` call so
+  there's only one staging path left.
+- **Renamed artboard left the old PNG on disk in incremental mode.** When
+  `state.json` was stale (e.g. a victim of the `.tmp` leak above) the
+  rename detector couldn't correlate the new manifest entry to the prior
+  key, and the incremental code path skips the full orphan sweep. Sync now
+  has a sha-based fallback: for each download-bound entry whose `sha256`
+  matches a stranded local PNG (one whose disk path is not in the current
+  manifest), we record a synthetic `RenameInfo` and prune the stale PNG.
+  Same-bytes + manifest-no-longer-references-that-path is unambiguous
+  evidence of a rename and never deletes anything the user still owns.
+
+### Added
+
+- **Startup `.tmp` janitor.** `magicpixel sync` (one-shot and `--watch`)
+  sweeps stale `<file>.<pid>.<hex>.tmp` files left over from prior crashed
+  or killed runs across `outDir/**`, `.magicpixel/`, and the project root.
+  Pattern is anchored (`\.\d+\.[0-9a-f]{16}\.tmp$`) so user files with
+  `.tmp` in the name are never touched, and a 30-second age floor prevents
+  any race with a concurrent in-flight write.
+- **`atomicWrite` now accepts `Uint8Array` in addition to `string`** so the
+  asset-bytes writer in `sync` can share the same cleanup-guaranteed
+  staging logic as every other writer.
+
 ## [0.5.0] — 2026-06-02
 
 ### Added

package/dist/commands/sync.js

@@ -1,7 +1,7 @@
 import kleur from 'kleur';
 import ora from 'ora';
 import { createHash } from 'node:crypto';
-import { mkdir, writeFile, unlink, rename, readdir, rm } from 'node:fs/promises';
+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';
@@ -10,11 +10,23 @@ import { fileSha256 } from '../util/hash.js';
 import { assetDiskPath, assetDiskPathFromKey, pruneEmptyDirs, walkOutDirPngs } from '../util/paths.js';
 import { createLimit } from '../util/limit.js';
 import { emitTypedIndex, ensureAgentsDoc, scanDiskAssets } from '../util/emitIndex.js';
-import { assertPathInsideRoot, tmpPathFor } from '../util/security.js';
+import { assertPathInsideRoot } from '../util/security.js';
+import { runTmpJanitor } from '../util/tmpJanitor.js';
 import { friendlyFsError } from '../util/errors.js';
 import { maxIsoTimestamp } from '../util/iso.js';
 import { formatBytes } from '../util/format.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
+    // (watch mode included) and only touches files older than 30s, so it can
+    // never race a concurrent in-flight write. See util/tmpJanitor.ts.
+    try {
+        const cfg = await loadConfig();
+        await runTmpJanitor(cfg.outDir);
+    }
+    catch {
+        /* janitor is best-effort — never let it block a sync */
+    }
     if (opts.watch) {
         await watchLoop(opts);
         return;
@@ -354,11 +366,58 @@ async function runOnce(opts, runOpts = {}) {
     // Orphan detection only when we have the full picture.
     // (Renames also produce a stale path on disk — collected separately below.)
     let orphans = [];
+    const remoteDiskPaths = new Set(manifest.map((e) => pathFor(e)));
+    // We walk local PNGs even in incremental mode so the sha-based rename
+    // fallback below has something to match against. The full-orphan path is
+    // still gated on `!since` to preserve incremental-mode safety (we never
+    // delete files outside what the current manifest delta touches).
+    const localPngs = await walkOutDirPngs(config.outDir);
     if (!since) {
-        const remoteDiskPaths = new Set(manifest.map((e) => pathFor(e)));
-        const localPngs = await walkOutDirPngs(config.outDir);
         orphans = localPngs.map((a) => a.abs).filter((p) => !remoteDiskPaths.has(p));
     }
+    // Heuristic-rename fallback for incremental mode.
+    //
+    // If `state.json` was lost or got out of sync (rare, but the 0.5.x leak of
+    // `state.json.<pid>.<hex>.tmp` files proved it happens in practice — see
+    // CHANGELOG 0.5.1), `previousAssets` won't have the mapping needed to mark
+    // a renamed artboard. The old `<oldSlug>.png` then lingers forever next to
+    // the new `<newSlug>.png` because incremental mode skips the full orphan
+    // sweep.
+    //
+    // Bridge that gap: for every download-bound entry, look for a stranded
+    // local PNG (path not in this manifest) whose sha256 matches the entry's.
+    // Same bytes + manifest no longer references that path = same artboard,
+    // renamed. We add the stranded path to `renameStalePaths` and record a
+    // RenameInfo so the CLI prints the migration hint.
+    if (since && toDownload.length > 0) {
+        const strandedBySha = new Map();
+        for (const local of localPngs) {
+            if (remoteDiskPaths.has(local.abs))
+                continue;
+            const sha = await fileSha256(local.abs);
+            if (sha)
+                strandedBySha.set(sha, local.abs);
+        }
+        if (strandedBySha.size > 0) {
+            const outRoot = resolve(process.cwd(), config.outDir);
+            const seenRenameIds = new Set(renamed.map((r) => r.id));
+            for (const entry of toDownload) {
+                if (!entry.sha256)
+                    continue;
+                if (seenRenameIds.has(entry.id))
+                    continue;
+                const strandedPath = strandedBySha.get(entry.sha256);
+                if (!strandedPath)
+                    continue;
+                // Derive the disk key from the stranded path so the rename hint reads
+                // naturally (`cards/artboard-1 → cards/tree`).
+                const rel = relative(outRoot, strandedPath).replace(/\\/g, '/');
+                const oldKey = rel.endsWith('.png') ? rel.slice(0, -4) : rel;
+                renamed.push({ id: entry.id, oldKey, newKey: entry.key });
+                seenRenameIds.add(entry.id);
+            }
+        }
+    }
     // Stale paths from detected renames (always pruned, even in incremental mode —
     // otherwise the old PNG silently lingers next to the renamed copy).
     const renameStalePaths = renamed
@@ -486,14 +545,23 @@ async function runOnce(opts, runOpts = {}) {
                         throw new Error(`sha256 mismatch (expected ${entry.sha256.slice(0, 12)}…, got ${actual.slice(0, 12)}…)`);
                     }
                 }
-                // Wrap any of mkdir/writeFile/rename so the user sees a friendly
+                // Wrap any of mkdir/writeFile so the user sees a friendly
                 // multi-line diagnostic instead of a raw `EACCES: permission denied`.
+                //
+                // NOTE: Asset PNGs deliberately use a direct writeFile rather than
+                // atomicWrite. Vite's chokidar watcher only suppresses atomic-rename
+                // unlink/add pairs when the tmp filename starts with '.' or ends
+                // with '~'; our pattern <name>.<pid>.<hex>.tmp matches neither, so
+                // rename-over emits unlink+add instead of change, which breaks
+                // instant HMR for image imports in the browser (user has to hard
+                // refresh to see the new asset). A torn write here is self-healing
+                // on the next watch tick (re-download by sha mismatch), so the
+                // atomicity guarantee isn't worth the HMR regression. Do not
+                // "fix" this back to atomicWrite without also changing the
+                // tmp-name pattern AND verifying HMR end-to-end in a consumer app.
                 try {
                     await mkdir(dirname(diskPath), { recursive: true });
-                    const tmp = tmpPathFor(diskPath);
-                    assertPathInsideRoot(tmp, resolve(process.cwd(), config.outDir), 'outDir');
-                    await writeFile(tmp, bytes);
-                    await rename(tmp, diskPath);
+                    await writeFile(diskPath, bytes);
                 }
                 catch (fsErr) {
                     throw friendlyFsError(fsErr, {

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

@@ -1,25 +1,57 @@
-import { writeFile, rename, chmod } from 'node:fs/promises';
+import { writeFile, rename, chmod, unlink } from 'node:fs/promises';
 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).
+ * 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` 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
+ * `rename` failure (FS hiccup, AV scan, racing writer, ENOSPC) leaks a
+ * `<path>.<pid>.<hex>.tmp` file forever — `saveState` runs every watch tick,
+ * so even a low failure rate accumulates hundreds of stale tmps over a long
+ * dev session and they're invisible to the `.png`-only orphan walker.
  */
 export async function atomicWrite(path, contents, opts = {}) {
     const tmp = tmpPathFor(path);
-    const writeOpts = opts.mode !== undefined ? { encoding: 'utf8', mode: opts.mode } : 'utf8';
-    await writeFile(tmp, contents, writeOpts);
-    if (opts.mode !== undefined) {
-        // Belt-and-suspenders: writeFile's `mode` only applies on create. If the
-        // tmp path was somehow pre-existing (collision is vanishingly unlikely
-        // given the pid+random suffix) the chmod ensures the perms land.
+    try {
+        if (typeof contents === 'string') {
+            const writeOpts = opts.mode !== undefined ? { encoding: 'utf8', mode: opts.mode } : 'utf8';
+            await writeFile(tmp, contents, writeOpts);
+        }
+        else {
+            const writeOpts = opts.mode !== undefined ? { mode: opts.mode } : undefined;
+            await writeFile(tmp, contents, writeOpts);
+        }
+        if (opts.mode !== undefined) {
+            // Belt-and-suspenders: writeFile's `mode` only applies on create. If the
+            // tmp path was somehow pre-existing (collision is vanishingly unlikely
+            // given the pid+random suffix) the chmod ensures the perms land.
+            try {
+                await chmod(tmp, opts.mode);
+            }
+            catch {
+                // Windows / read-only FS — ignore.
+            }
+        }
+        await rename(tmp, path);
+    }
+    catch (err) {
+        // Best-effort cleanup. We don't want a cleanup failure (e.g. tmp was
+        // never created because writeFile threw on the very first syscall) to
+        // mask the real error the caller cares about.
         try {
-            await chmod(tmp, opts.mode);
+            await unlink(tmp);
         }
         catch {
-            // Windows / read-only FS — ignore.
+            /* ignore — tmp may not exist */
         }
+        throw err;
     }
-    await rename(tmp, path);
 }

package/dist/util/tmpJanitor.js

@@ -0,0 +1,80 @@
+import { readdir, stat, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * Pattern produced by `tmpPathFor`: `<basename>.<pid>.<16-hex>.tmp`.
+ * Anchored at both ends to avoid matching user files that happen to contain
+ * the substring.
+ */
+const TMP_SUFFIX_RE = /\.\d+\.[0-9a-f]{16}\.tmp$/;
+/**
+ * Stale-tmp age threshold. Any tmp file modified within this window could
+ * still belong to a concurrent writer (another CLI process, or an in-flight
+ * write in this process whose `rename` is about to land). Skipping recent
+ * files is the safety net that makes the janitor side-effect-free for the
+ * happy path.
+ */
+const MIN_STALE_AGE_MS = 30_000;
+/**
+ * Walk `dirs` recursively (one level deep is enough for our layout — the
+ * outDir is `src/assets/magicpixel/<folder>/*.png` and state lives in
+ * `.magicpixel/`). Returns absolute paths of removed files. Errors during
+ * readdir/unlink are swallowed individually so one unreadable directory
+ * can't abort the whole sweep.
+ *
+ * Exported for tests; the entry point used by sync is `runTmpJanitor`.
+ */
+export async function sweepTmpFiles(dir, now = Date.now(), minAgeMs = MIN_STALE_AGE_MS) {
+    const removed = [];
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return removed;
+    }
+    for (const ent of entries) {
+        const full = join(dir, ent.name);
+        if (ent.isDirectory()) {
+            // One level of recursion (e.g. outDir/<folder>/). Deeper trees are not
+            // produced by atomicWrite callers.
+            const nested = await sweepTmpFiles(full, now, minAgeMs);
+            for (const p of nested)
+                removed.push(p);
+            continue;
+        }
+        if (!ent.isFile())
+            continue;
+        if (!TMP_SUFFIX_RE.test(ent.name))
+            continue;
+        try {
+            const st = await stat(full);
+            if (now - st.mtimeMs < minAgeMs)
+                continue;
+            await unlink(full);
+            removed.push(full);
+        }
+        catch {
+            /* ignore — file may have just been renamed away by a concurrent writer */
+        }
+    }
+    return removed;
+}
+/**
+ * Run the janitor across the directories that atomicWrite targets land in:
+ *   - `<outDir>/**` — asset PNGs (one level of folders).
+ *   - `<cwd>/.magicpixel/` — state.json + credentials.
+ *   - `<cwd>/` — package.json, magicpixel.json, AGENTS.md.
+ *
+ * Side-effect-free for the happy path: the `MIN_STALE_AGE_MS` floor prevents
+ * any race with a concurrent in-flight write.
+ */
+export async function runTmpJanitor(outDir, cwd = process.cwd()) {
+    const dirs = [outDir, join(cwd, '.magicpixel'), cwd];
+    const all = [];
+    for (const d of dirs) {
+        const r = await sweepTmpFiles(d);
+        for (const p of r)
+            all.push(p);
+    }
+    return all;
+}

package/package.json

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