@magicpixelart/cli 0.5.7 → 0.5.9

package/dist/util/gameScan.js

@@ -0,0 +1,177 @@
+/**
+ * Game-tree index for opt-in connect. Walks the project/package (including
+ * hidden content dirs like `.SpineRaw_*`) but never copies files. `connect`
+ * globs select a working set; sync writes back to those original paths.
+ */
+import { existsSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { relative, resolve } from 'node:path';
+import { isEngineKind, resolveChildDir } from './framework.js';
+import { assertPathInsideRoot, sanitizeSourceRel } from './security.js';
+import { gameImportAdoptPath } from './pushPlan.js';
+import { matchGlob } from './globMatch.js';
+import { createLimit } from './limit.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',
+    'node_modules',
+    'magicpixel',
+]);
+/**
+ * Dot-directories we never walk. Other hidden folders (e.g. `.SpineRaw_*`)
+ * are scanned — Unity packages often stash sprites there.
+ */
+export const GAME_SCAN_SKIP_HIDDEN = new Set([
+    '.git',
+    '.svn',
+    '.hg',
+    '.magicpixel',
+    '.vs',
+    '.vscode',
+    '.idea',
+    '.cursor',
+    '.config',
+    '.cache',
+]);
+/** Parallel directory reads while walking the game tree. */
+const SCAN_WALK_CONCURRENCY = 8;
+/** Cap on the search index (whole tree). Connect uses the same ceiling. */
+export const MAX_GAME_INDEX = 10_000;
+/** Cap on PNGs ingested for one working-set connect / push. */
+export const MAX_GAME_CONNECT = MAX_GAME_INDEX;
+export const GAME_INDEX_CAP_HINT = `Game index hit ${MAX_GAME_INDEX} PNGs — later files aren't searchable or connectable.`;
+export function connectCapMessage(total, ingested) {
+    return (`${total} PNGs match the working set — ingesting the first ${ingested} (cap ${MAX_GAME_CONNECT}). ` +
+        `Narrow the glob, or add another connect pattern for the rest.`);
+}
+export function gameScanRoot(kind) {
+    switch (kind) {
+        case 'Unity':
+            return 'Assets';
+        case 'Godot':
+            return 'assets';
+        case 'GameMaker':
+            return 'datafiles';
+        default:
+            return null;
+    }
+}
+function shouldSkipDir(name) {
+    const n = name.toLowerCase();
+    if (GAME_SCAN_SKIP_DIRS.has(n))
+        return true;
+    if (GAME_SCAN_SKIP_HIDDEN.has(n))
+        return true;
+    if (n.startsWith('.git'))
+        return true;
+    return false;
+}
+function importRel(abs, cwd, assetRoot) {
+    if (assetRoot) {
+        const rootNorm = assetRoot.replace(/\\/g, '/').toLowerCase();
+        const absNorm = abs.replace(/\\/g, '/').toLowerCase();
+        if (absNorm === rootNorm || absNorm.startsWith(`${rootNorm}/`)) {
+            return relative(assetRoot, abs).replace(/\\/g, '/');
+        }
+    }
+    return relative(cwd, abs).replace(/\\/g, '/');
+}
+function toEntry(abs, cwdAbs, assetRoot) {
+    const sourceRel = sanitizeSourceRel(relative(cwdAbs, abs).replace(/\\/g, '/'));
+    if (!sourceRel)
+        return null;
+    const adoptRel = importRel(abs, cwdAbs, assetRoot);
+    const relKey = adoptRel.replace(/\.png$/i, '');
+    const adopted = gameImportAdoptPath(relKey.split('/'));
+    if (adopted.path.length < 2 || adopted.path.some((s) => !s))
+        return null;
+    return { abs, sourceRel, adoptRel, key: adopted.path.join('/') };
+}
+/** Walk the engine tree and return index entries. Does not copy files. */
+export async function indexGamePngs(kind, cwd = process.cwd(), outDir = '') {
+    const empty = { files: [], capped: false };
+    if (!isEngineKind(kind))
+        return empty;
+    const scanRoot = resolve(cwd);
+    if (!existsSync(scanRoot))
+        return empty;
+    const destNorm = outDir ? resolve(cwd, outDir).replace(/\\/g, '/').toLowerCase() : '';
+    const namedRoot = gameScanRoot(kind);
+    const assetRoot = namedRoot ? resolveChildDir(cwd, namedRoot) : null;
+    const found = [];
+    const io = createLimit(SCAN_WALK_CONCURRENCY);
+    await walkPngs(scanRoot, scanRoot, destNorm, found, MAX_GAME_INDEX + 1, io);
+    found.sort((a, b) => a.localeCompare(b));
+    const capped = found.length > MAX_GAME_INDEX;
+    if (capped)
+        found.length = MAX_GAME_INDEX;
+    const files = [];
+    for (const abs of found) {
+        const entry = toEntry(abs, scanRoot, assetRoot);
+        if (entry)
+            files.push(entry);
+    }
+    return { files, capped };
+}
+/** Filter the index by connect globs (cwd-relative or asset-root-relative). */
+export function matchConnectGlobs(index, globs, max = MAX_GAME_CONNECT) {
+    if (globs.length === 0)
+        return { entries: [], total: 0, capped: false };
+    const matched = index.files.filter((e) => globs.some((g) => matchGlob(e.sourceRel, g) || matchGlob(e.adoptRel, g)));
+    matched.sort((a, b) => a.sourceRel.localeCompare(b.sourceRel));
+    const total = matched.length;
+    const capped = total > max;
+    return { entries: capped ? matched.slice(0, max) : matched, total, capped };
+}
+export function searchGameIndex(index, query) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return [];
+    return index.files.filter((e) => e.sourceRel.toLowerCase().includes(q) || e.key.includes(q) || e.adoptRel.toLowerCase().includes(q));
+}
+async function walkPngs(dir, root, destNorm, out, limit, io) {
+    if (out.length >= limit)
+        return;
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    const subdirs = [];
+    for (const ent of entries) {
+        if (out.length >= limit)
+            return;
+        if (ent.isSymbolicLink())
+            continue;
+        const full = resolve(dir, ent.name);
+        try {
+            assertPathInsideRoot(full, root, 'scan');
+        }
+        catch {
+            continue;
+        }
+        if (ent.isDirectory()) {
+            if (shouldSkipDir(ent.name))
+                continue;
+            if (destNorm && full.replace(/\\/g, '/').toLowerCase() === destNorm)
+                continue;
+            subdirs.push(full);
+        }
+        else if (ent.isFile() && ent.name.toLowerCase().endsWith('.png')) {
+            out.push(full);
+        }
+    }
+    if (subdirs.length === 0 || out.length >= limit)
+        return;
+    await Promise.all(subdirs.map((d) => io(() => walkPngs(d, root, destNorm, out, limit, io))));
+}

package/dist/util/globMatch.js

@@ -0,0 +1,50 @@
+/**
+ * Small picomatch subset (`*`, `**`, `?`) so `connect` globs work without
+ * adding a runtime dependency. Case-insensitive; backslashes treated as `/`.
+ */
+const regexCache = new Map();
+export function matchGlob(path, pattern) {
+    const p = path.replace(/\\/g, '/').replace(/^\.\//, '');
+    const g = pattern.replace(/\\/g, '/').replace(/^\.\//, '');
+    if (!g)
+        return false;
+    let re = regexCache.get(g);
+    if (!re) {
+        re = globToRegExp(g);
+        regexCache.set(g, re);
+    }
+    return re.test(p);
+}
+function globToRegExp(glob) {
+    let out = '^';
+    for (let i = 0; i < glob.length;) {
+        const c = glob[i];
+        if (c === '*' && glob[i + 1] === '*') {
+            if (glob[i + 2] === '/') {
+                out += '(?:.*/)?';
+                i += 3;
+            }
+            else {
+                out += '.*';
+                i += 2;
+            }
+        }
+        else if (c === '*') {
+            out += '[^/]*';
+            i += 1;
+        }
+        else if (c === '?') {
+            out += '[^/]';
+            i += 1;
+        }
+        else {
+            if (/[.+^${}()|[\]\\]/.test(c))
+                out += `\\${c}`;
+            else
+                out += c;
+            i += 1;
+        }
+    }
+    out += '$';
+    return new RegExp(out, 'i');
+}

package/dist/util/hash.js

@@ -1,9 +1,41 @@
 import { createHash } from 'node:crypto';
-import { readFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-export async function fileSha256(path) {
-    if (!existsSync(path))
+import { lstat, readFile } from 'node:fs/promises';
+/** Process-lifetime cache: skip re-reading a PNG when mtime+size are unchanged. */
+const cache = new Map();
+export function clearFileHashCache() {
+    cache.clear();
+}
+export async function hashFile(path, hint) {
+    let st;
+    try {
+        st = await lstat(path);
+    }
+    catch {
+        cache.delete(path);
+        return null;
+    }
+    if (!st.isFile() || st.isSymbolicLink()) {
+        cache.delete(path);
         return null;
+    }
+    if (hint && hint.mtimeMs === st.mtimeMs && hint.size === st.size) {
+        const rec = { sha256: hint.sha256, mtimeMs: st.mtimeMs, size: st.size };
+        cache.set(path, rec);
+        return rec;
+    }
+    const hit = cache.get(path);
+    if (hit && hit.mtimeMs === st.mtimeMs && hit.size === st.size)
+        return hit;
     const buf = await readFile(path);
-    return createHash('sha256').update(buf).digest('hex');
+    const rec = {
+        sha256: createHash('sha256').update(buf).digest('hex'),
+        mtimeMs: st.mtimeMs,
+        size: st.size,
+    };
+    cache.set(path, rec);
+    return rec;
+}
+export async function fileSha256(path) {
+    const hashed = await hashFile(path);
+    return hashed?.sha256 ?? null;
 }

package/dist/util/pushPlan.js

@@ -26,13 +26,107 @@ export function pushSlug(raw) {
         .replace(/-+$/g, '');
 }
 export const MAX_PUSH_PATH_SEGMENTS = 8;
+/**
+ * Connected-section root used when a Unity PNG sits at the scan root
+ * (`Assets/hero.png`) with no parent folder to mirror.
+ */
+export const GAME_IMPORT_ROOT_FOLDER = 'Game';
+/**
+ * Unity/Godot/GameMaker layout: parent dirs become library folders (flagged
+ * Sync to Unity → Connected), and the PNG is a one-artboard document.
+ * `Sprites/hero.png` → folder Sprites / doc hero — not a root "Sprites"
+ * document, which would land in Files and leave Connected empty.
+ */
+export function gameImportAdoptPath(segments) {
+    const parts = segments.filter(Boolean);
+    const file = parts[parts.length - 1] ?? '';
+    let folders = parts.length > 1 ? parts.slice(0, -1) : [GAME_IMPORT_ROOT_FOLDER];
+    const maxFolders = MAX_PUSH_PATH_SEGMENTS - 2;
+    if (folders.length > maxFolders)
+        folders = folders.slice(-maxFolders);
+    const pathNames = [...folders, file, file];
+    return { path: pathNames.map(pushSlug), pathNames, name: file };
+}
+/** Disk path relative to outDir for a Unity-imported PNG (`sprites/hero/hero.png`). */
+export function gameImportDiskRel(segments) {
+    return `${gameImportAdoptPath(segments).path.join('/')}.png`;
+}
+/**
+ * Bytes last known on disk for skip decisions. Cloud `sha256` is the conflict
+ * baseline, not the original game PNG — connected sprites must not treat a
+ * composite mismatch as a local edit.
+ */
+export function lastPushedDiskSha(known, opts = {}) {
+    if (known.diskSha256)
+        return known.diskSha256;
+    if (known.sourceRel || opts.connected)
+        return undefined;
+    return known.sha256;
+}
+export function indexSyncedBySourceRel(synced) {
+    const map = new Map();
+    for (const [key, sprite] of Object.entries(synced)) {
+        if (sprite.sourceRel)
+            map.set(sprite.sourceRel, key);
+    }
+    return map;
+}
+/** State key for a candidate: exact key, else the row that still points at this game path. */
+export function resolveSyncedKey(candidate, synced, byRel = indexSyncedBySourceRel(synced)) {
+    if (synced[candidate.key])
+        return candidate.key;
+    if (candidate.sourceRel)
+        return byRel.get(candidate.sourceRel);
+    return undefined;
+}
+/**
+ * Record on-disk sha256 onto synced rows so the next push can skip without
+ * comparing against a cloud composite. Only updates keys already in state.
+ */
+export function applyDiskFingerprints(synced, fingerprints) {
+    const byRel = indexSyncedBySourceRel(synced);
+    let next = null;
+    for (const fp of fingerprints) {
+        const src = next ?? synced;
+        const stateKey = resolveSyncedKey(fp, src, byRel);
+        if (!stateKey)
+            continue;
+        const known = src[stateKey];
+        if (!known)
+            continue;
+        if (known.diskSha256 === fp.diskSha256 &&
+            (fp.diskMtimeMs == null || known.diskMtimeMs === fp.diskMtimeMs) &&
+            (fp.diskSize == null || known.diskSize === fp.diskSize)) {
+            continue;
+        }
+        if (!next)
+            next = { ...synced };
+        next[stateKey] = {
+            ...known,
+            diskSha256: fp.diskSha256,
+            ...(fp.diskMtimeMs != null ? { diskMtimeMs: fp.diskMtimeMs } : {}),
+            ...(fp.diskSize != null ? { diskSize: fp.diskSize } : {}),
+        };
+    }
+    return next ? { next, changed: true } : { next: synced, changed: false };
+}
 export function planPush(candidates, synced, opts = {}) {
     const state = synced ?? {};
+    const byRel = indexSyncedBySourceRel(state);
     const out = [];
     for (const c of candidates) {
-        const known = state[c.key];
+        const stateKey = resolveSyncedKey(c, state, byRel);
+        const known = stateKey ? state[stateKey] : undefined;
         if (known) {
-            if (known.sha256 === c.diskSha256) {
+            const connected = Boolean(c.sourceRel || opts.folderTreeKeys?.has(c.key) || (stateKey != null && opts.folderTreeKeys?.has(stateKey)));
+            const lastDisk = lastPushedDiskSha(known, { connected });
+            if (lastDisk === c.diskSha256) {
+                out.push({ kind: 'skip', key: c.key, reason: 'unchanged' });
+                continue;
+            }
+            if (lastDisk === undefined) {
+                // Connected original with no disk baseline yet. Ingest's composite
+                // sha is not the game file — seeding happens in `applyDiskFingerprints`.
                 out.push({ kind: 'skip', key: c.key, reason: 'unchanged' });
                 continue;
             }
@@ -55,9 +149,25 @@ 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. Game-tree PNGs keep their folders so they show
+        // up under Connected. MagicPixel's own `doc/artboard.png` layout stays
+        // a two-segment path (document + artboard at library root / in-folder).
+        if (opts.folderTreeKeys?.has(c.key)) {
+            const adopted = gameImportAdoptPath(c.segments);
+            if (adopted.path.length < 2 || adopted.path.some((s) => !s)) {
+                out.push({ kind: 'skip', key: c.key, reason: 'unusable-path' });
+                continue;
+            }
+            out.push({ kind: 'adopt', key: c.key, ...adopted });
+            continue;
+        }
+        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/dist/util/security.js

@@ -1,5 +1,6 @@
 import { randomBytes } from 'node:crypto';
-import { isAbsolute, relative, resolve } from 'node:path';
+import { lstat, realpath } from 'node:fs/promises';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
 /** Max PNG payload per asset (64 MiB). */
 export const MAX_ASSET_BYTES = 64 * 1024 * 1024;
 const SHA256_RE = /^[a-f0-9]{64}$/i;
@@ -128,12 +129,101 @@ export async function readBodyWithLimit(res, maxBytes) {
 }
 /** Max length of a user-supplied picomatch glob; shared with config.ts. */
 export const MAX_GLOB_LEN = 256;
+/** Max cwd-relative game PNG path persisted or written back. */
+export const MAX_SOURCE_REL = 512;
+/**
+ * Game write-back path must be a relative PNG with no `..` / empty / absolute
+ * segments. Rejects `Assets/../package.json`-style tricks that `resolve()`
+ * would otherwise normalize back inside the project.
+ */
+export function sanitizeSourceRel(rel) {
+    if (!rel || typeof rel !== 'string')
+        return null;
+    const g = rel.trim().replace(/\\/g, '/').replace(/^\.\//, '');
+    if (!g || g.includes('\0') || g.length > MAX_SOURCE_REL)
+        return null;
+    if (isAbsolute(g) || /^[a-zA-Z]:/.test(g))
+        return null;
+    const parts = g.split('/');
+    if (parts.some((s) => s === '' || s === '.' || s === '..'))
+        return null;
+    if (!g.toLowerCase().endsWith('.png'))
+        return null;
+    return g;
+}
+/**
+ * Refuse to read or write through a symlink (or a parent symlink that
+ * realpath-escapes the project). Closes the window where a `.png` is swapped
+ * for a link after the index walk skipped `isSymbolicLink()`.
+ */
+export async function assertSafeIoPath(targetPath, rootDir, opts = {}) {
+    const label = opts.label ?? 'project';
+    const verb = opts.forWrite ? 'write' : 'read';
+    const root = resolve(rootDir);
+    const target = resolve(targetPath);
+    assertPathInsideRoot(target, root, label);
+    // Compare symlink-resolved paths against the real project root. On macOS
+    // `tmpdir()` is `/var/folders` → `/private/var/folders`; lexical `resolve`
+    // alone would reject a realpath that is still the same directory.
+    let rootReal = root;
+    try {
+        rootReal = await realpath(root);
+    }
+    catch {
+        // Root missing — lexical check above already ran.
+    }
+    let st;
+    try {
+        st = await lstat(target);
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+        st = null;
+    }
+    if (st) {
+        if (st.isSymbolicLink()) {
+            throw new Error(`refusing to ${verb} through a symlink (${relative(process.cwd(), target) || target}).\n` +
+                `  Fix: replace the symlink with a regular .png inside the project.`);
+        }
+        if (!st.isFile()) {
+            throw new Error(`refusing to ${verb} a non-file (${relative(process.cwd(), target) || target}).`);
+        }
+        const real = await realpath(target);
+        assertPathInsideRoot(real, rootReal, label);
+        return;
+    }
+    let dir = dirname(target);
+    while (true) {
+        try {
+            const realDir = await realpath(dir);
+            const rest = relative(dir, target);
+            if (rest === '' || rest.startsWith('..') || isAbsolute(rest)) {
+                throw new Error(`refusing to ${verb} outside ${label}.`);
+            }
+            assertPathInsideRoot(resolve(realDir, rest), rootReal, label);
+            return;
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+            const parent = dirname(dir);
+            if (parent === dir) {
+                throw new Error(`refusing to ${verb}: could not resolve parent of ${target}.`);
+            }
+            dir = parent;
+        }
+    }
+}
 /** Validate a user-supplied picomatch glob from the CLI. */
 export function assertSafeGlob(glob) {
     const g = glob.trim();
     if (!g || g.length > MAX_GLOB_LEN || g.includes('\0')) {
         throw new Error(`invalid glob pattern (empty, too long, or contains null bytes).`);
     }
+    if (g.split(/[/\\]/).some((seg) => seg === '..')) {
+        throw new Error(`invalid glob pattern (must not contain "..").`);
+    }
     return g;
 }
 /**

package/dist/util/syncPath.js

@@ -0,0 +1,76 @@
+import { isAbsolute, relative, resolve } from 'node:path';
+import { assetDiskPathFromKey } from './paths.js';
+import { assertPathInsideRoot, sanitizeSourceRel } from './security.js';
+export { sanitizeSourceRel } from './security.js';
+/** Resolve a cwd-relative game path; refuse anything that escapes the project. */
+export function resolveProjectRel(rel, cwd = process.cwd()) {
+    const safe = sanitizeSourceRel(rel);
+    if (!safe) {
+        throw new Error(`refusing unsafe game path (${rel}).\n` +
+            `  Fix: sourceRel must be a relative .png inside the project, with no "..".`);
+    }
+    const abs = resolve(cwd, safe);
+    assertPathInsideRoot(abs, resolve(cwd), 'project');
+    return abs;
+}
+/**
+ * Write-back map from the live connect index. Persisted `sourceRel` is only
+ * used as a cloud-key alias when that path is still in the working set —
+ * a hand-edited state.json cannot invent a new target file.
+ */
+export function collectSourceRelMap(connected, synced) {
+    const map = new Map();
+    const liveRels = new Set();
+    for (const e of connected) {
+        const rel = sanitizeSourceRel(e.sourceRel);
+        if (!rel)
+            continue;
+        map.set(e.key, rel);
+        liveRels.add(rel);
+    }
+    if (synced) {
+        for (const [key, sprite] of Object.entries(synced)) {
+            const rel = sanitizeSourceRel(sprite.sourceRel);
+            if (rel && liveRels.has(rel))
+                map.set(key, rel);
+        }
+    }
+    return map;
+}
+/**
+ * When the cloud assigned a different composite key than the index key,
+ * push under the cloud key so we update instead of adopting a duplicate.
+ */
+export function remapAbsToCloudKeys(absByKey, connected, synced) {
+    if (!synced)
+        return;
+    const relToLiveKey = new Map();
+    for (const e of connected) {
+        const rel = sanitizeSourceRel(e.sourceRel);
+        if (rel)
+            relToLiveKey.set(rel, e.key);
+    }
+    for (const [cloudKey, sprite] of Object.entries(synced)) {
+        const rel = sanitizeSourceRel(sprite.sourceRel);
+        if (!rel)
+            continue;
+        const liveKey = relToLiveKey.get(rel);
+        if (!liveKey || liveKey === cloudKey)
+            continue;
+        const abs = absByKey.get(liveKey) ?? absByKey.get(cloudKey);
+        if (!abs)
+            continue;
+        absByKey.set(cloudKey, abs);
+        absByKey.delete(liveKey);
+    }
+}
+export function syncDiskPathFromKey(outDir, key, sourceByKey, cwd = process.cwd()) {
+    const rel = sourceByKey.get(key);
+    if (rel)
+        return resolveProjectRel(rel, cwd);
+    return assetDiskPathFromKey(outDir, key, cwd);
+}
+export function isPathInside(target, root) {
+    const rel = relative(resolve(root), resolve(target));
+    return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+}

package/package.json

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