@magicpixelart/cli 0.3.0 → 0.4.0

package/dist/util/emitIndex.js

@@ -1,7 +1,10 @@
-import { readFile, readdir, writeFile } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { assertPathInsideRoot, assertSafeAssetSegments } from './security.js';
+import { assertSafeAssetSegments } from './security.js';
+import { atomicWrite } from './atomicWrite.js';
+import { walkOutDirPngs } from './paths.js';
+import { isStaticOutDir } from './framework.js';
 const AGENT_HEADER = [
     '// 👋 AI agents: import sprites by key, e.g.',
     '//   import { MagicPixelAssets } from "<this-dir>";',
@@ -18,41 +21,15 @@ const AGENT_HEADER = [
  * manifest call left the barrel stale while the PNGs on disk were fresh. We
  * now derive the index purely from the filesystem so it can never disagree
  * with what bundlers will see.
+ *
+ * Delegates the actual walk to the shared `walkOutDirPngs` helper (also used
+ * by sync.ts's orphan scan) so both code paths share one symlink/security
+ * policy.
  */
 export async function scanDiskAssets(outDir, cwd = process.cwd()) {
-    const root = resolve(cwd, outDir);
-    if (!existsSync(root))
-        return [];
-    const out = [];
-    async function walk(dir, folderParts) {
-        const entries = await readdir(dir, { withFileTypes: true });
-        for (const ent of entries) {
-            if (ent.isSymbolicLink())
-                continue;
-            const full = resolve(dir, ent.name);
-            try {
-                assertPathInsideRoot(full, root, 'outDir');
-            }
-            catch {
-                continue;
-            }
-            if (ent.isDirectory()) {
-                // Skip the id sidecar dir or any dotted folders — never user assets.
-                if (ent.name.startsWith('.'))
-                    continue;
-                await walk(full, [...folderParts, ent.name]);
-            }
-            else if (ent.isFile() && ent.name.toLowerCase().endsWith('.png')) {
-                const slug = ent.name.slice(0, -4);
-                const folder = folderParts.length ? folderParts.join('/') : null;
-                const key = folder ? `${folder}/${slug}` : slug;
-                out.push({ key, folder, slug });
-            }
-        }
-    }
-    await walk(root, []);
-    out.sort((a, b) => a.key.localeCompare(b.key));
-    return out;
+    const found = await walkOutDirPngs(outDir, cwd);
+    // No sort here — `emitTypedIndex` already owns the canonical key ordering.
+    return found.map(({ key, folder, slug }) => ({ key, folder, slug }));
 }
 /**
  * Emit `<outDir>/index.ts` with a typed map of every asset key → URL, plus an
@@ -66,17 +43,18 @@ export async function scanDiskAssets(outDir, cwd = process.cwd()) {
  * time. No runtime, no bundler config.
  */
 export async function emitTypedIndex(outDir, entries, cwd = process.cwd()) {
-    // Dedupe by key. The disk scan can't actually produce duplicates, but guard
-    // anyway so a future caller passing manifest entries can't break TS compile.
+    // Sort by key for stable output. The disk walker can't actually produce
+    // duplicate keys (one PNG per filesystem path), but a future caller passing
+    // manifest entries could — silently skip duplicates so we never emit an
+    // invalid TS object literal.
+    const sorted = [];
     const seen = new Set();
-    const sorted = [...entries]
-        .sort((a, b) => a.key.localeCompare(b.key))
-        .filter((e) => {
+    for (const e of [...entries].sort((a, b) => a.key.localeCompare(b.key))) {
         if (seen.has(e.key))
-            return false;
+            continue;
         seen.add(e.key);
-        return true;
-    });
+        sorted.push(e);
+    }
     const lines = [
         '// AUTOGENERATED by @magicpixelart/cli. Do not edit.',
         '// Re-runs of `magicpixel sync` overwrite this file.',
@@ -132,9 +110,10 @@ export async function emitTypedIndex(outDir, entries, cwd = process.cwd()) {
             // fall through and overwrite
         }
     }
-    await writeFile(path, next, 'utf8');
+    await atomicWrite(path, next);
     return path;
 }
+// (atomicWrite extracted to util/atomicWrite.ts and shared across writers.)
 /**
  * Ensure an `AGENTS.md` at the repo root nudges AI tools (Lovable, Cursor,
  * Claude Code, …) toward the typed index. Idempotent:
@@ -145,48 +124,77 @@ export async function emitTypedIndex(outDir, entries, cwd = process.cwd()) {
  */
 export async function ensureAgentsDoc(outDir, cwd = process.cwd()) {
     const path = resolve(cwd, 'AGENTS.md');
-    const importPath = guessImportPath(outDir);
-    const section = renderAgentsSection(importPath);
+    const section = renderAgentsSection(outDir);
     const marker = '<!-- magicpixel:start -->';
     if (!existsSync(path)) {
-        await writeFile(path, `# AGENTS\n\n${section}\n`, 'utf8');
+        await atomicWrite(path, `# AGENTS\n\n${section}\n`);
         return 'created';
     }
     const current = await readFile(path, 'utf8');
     if (current.includes(marker))
         return 'unchanged';
     const sep = current.endsWith('\n') ? '\n' : '\n\n';
-    await writeFile(path, current + sep + section + '\n', 'utf8');
+    await atomicWrite(path, current + sep + section + '\n');
     return 'appended';
 }
-function renderAgentsSection(importPath) {
+/**
+ * Resolve how PNGs under `outDir` are referenced by application code. Two
+ * cases:
+ *   - `public/...` or `static/...` (Next/Astro/Nuxt/CRA/SvelteKit) → these
+ *     are served as static assets at the URL root, so the correct reference
+ *     is an ABSOLUTE URL like `/magicpixel/items/tree.png`.
+ *   - everything else → bundler-importable; emit an `import { … } from
+ *     '@/...' | './...'` snippet that hashes the URL at build time.
+ */
+function resolveAssetReference(outDir) {
+    const norm = outDir.replace(/\\/g, '/').replace(/^\.\//, '');
+    if (isStaticOutDir(outDir)) {
+        // Strip the leading `public/` or `static/` — these dirs are served at the URL root.
+        const baseUrl = '/' + norm.replace(/^(public|static)\//, '');
+        return { mode: 'url', baseUrl };
+    }
+    // `src/...` is conventionally aliased to `@/...` in Vite/Next/etc.
+    if (norm.startsWith('src/'))
+        return { mode: 'import', importPath: `@/${norm.slice(4)}` };
+    return { mode: 'import', importPath: `./${norm}` };
+}
+function renderAgentsSection(outDir) {
+    const ref = resolveAssetReference(outDir);
+    const body = ref.mode === 'url'
+        ? [
+            `Pixel-art assets are synced to \`${outDir}\` by \`@magicpixelart/cli\`. They are`,
+            `plain PNGs served at the URL root — reference them by absolute path:`,
+            '',
+            '```tsx',
+            `<img src="${ref.baseUrl}/items/tree.png" />`,
+            '```',
+            '',
+            `Files live on disk at \`${outDir}/<folder>/<slug>.png\` so any path you see in the`,
+            'MagicPixel editor maps 1:1 to a URL.',
+        ]
+        : [
+            'Pixel-art assets are synced to disk by `@magicpixelart/cli`. They are plain PNGs you can `import`.',
+            '',
+            '```ts',
+            `// 1) Import by key (matches the folder/slug shown in the MagicPixel editor):`,
+            `import { MagicPixelAssets } from "${ref.importPath}";`,
+            `<img src={MagicPixelAssets["items/tree"]} />`,
+            '',
+            '// 2) Import by id (survives renames — pin imports that move around):',
+            `import { MagicPixelAssetsById } from "${ref.importPath}";`,
+            `<img src={MagicPixelAssetsById["<asset-uuid>"]} />`,
+            '```',
+            '',
+            'When you rename or move an asset, `magicpixel sync` prints both the old → new key',
+            'and the matching `MagicPixelAssetsById[...]` hint so you can pick whichever you prefer.',
+        ];
     return [
         '<!-- magicpixel:start -->',
         '## MagicPixel sprites',
         '',
-        'Pixel-art assets are synced to disk by `@magicpixelart/cli`. They are plain PNGs you can `import`.',
-        '',
-        '```ts',
-        `// 1) Import by key (matches the folder/slug shown in the MagicPixel editor):`,
-        `import { MagicPixelAssets } from "${importPath}";`,
-        `<img src={MagicPixelAssets["items/tree"]} />`,
-        '',
-        '// 2) Import by id (survives renames — pin imports that move around):',
-        `import { MagicPixelAssetsById } from "${importPath}";`,
-        `<img src={MagicPixelAssetsById["<asset-uuid>"]} />`,
-        '```',
-        '',
-        'When you rename or move an asset, `magicpixel sync` prints both the old → new key',
-        'and the matching `MagicPixelAssetsById[...]` hint so you can pick whichever you prefer.',
+        ...body,
         '',
         'Keep the watcher running while you edit: `npm run magicpixel:watch`.',
         '<!-- magicpixel:end -->',
     ].join('\n');
 }
-function guessImportPath(outDir) {
-    const norm = outDir.replace(/\\/g, '/').replace(/^\.\//, '');
-    // `src/...` is conventionally aliased to `@/...` in Vite/Next/etc.
-    if (norm.startsWith('src/'))
-        return `@/${norm.slice(4)}`;
-    return `./${norm}`;
-}

package/dist/util/errors.js

@@ -0,0 +1,49 @@
+import { relative } from 'node:path';
+/**
+ * Filesystem error codes that indicate a permission/lock problem rather than a
+ * bug in our code. We rewrite these into multi-line, action-oriented messages
+ * so a non-technical user can fix them without a Stack Overflow detour.
+ */
+const FS_PERMISSION_CODES = new Set(['EACCES', 'EPERM', 'EROFS', 'EBUSY', 'ETXTBSY']);
+/**
+ * Returns `true` if the error is a filesystem permission error we know how to
+ * rewrite. Useful for `try { … } catch (e) { if (isFsPermissionError(e)) … }`.
+ */
+export function isFsPermissionError(e) {
+    return !!e && typeof e === 'object' && 'code' in e && FS_PERMISSION_CODES.has(e.code ?? '');
+}
+/**
+ * Wrap a filesystem permission error in a friendly, paste-to-AI message.
+ * Returns the original error untouched if the code isn't one we recognize, so
+ * callers can blindly `throw friendlyFsError(e, …)` without losing detail.
+ */
+export function friendlyFsError(e, ctx) {
+    if (!isFsPermissionError(e))
+        return e instanceof Error ? e : new Error(String(e));
+    const code = e.code ?? 'EACCES';
+    const relPath = (() => {
+        try {
+            return relative(process.cwd(), ctx.path) || ctx.path;
+        }
+        catch {
+            return ctx.path;
+        }
+    })();
+    const lines = [`${ctx.operation} failed (${code}): ${relPath}`];
+    if (code === 'EROFS') {
+        lines.push('  Fix: outDir is on a read-only filesystem. Move it under your project source tree.');
+    }
+    else if (code === 'EBUSY' || code === 'ETXTBSY') {
+        lines.push('  Fix: close any editor or program holding the file open and re-run.');
+        lines.push('       (On Windows, OneDrive/Dropbox can also lock files briefly.)');
+    }
+    else {
+        // EACCES / EPERM
+        lines.push('  Fix: check that you can write to this path.');
+        lines.push('    • Linux/macOS:  chmod -R u+w <path>  (or run from a different shell)');
+        lines.push('    • Windows:      close OneDrive/your editor, or move outDir out of a synced folder');
+    }
+    if (ctx.hint)
+        lines.push(`  ${ctx.hint}`);
+    return new Error(lines.join('\n'));
+}

package/dist/util/flagValidators.js

@@ -0,0 +1,49 @@
+/**
+ * Validators for `commander` `.option()` parsers, extracted so they can be
+ * unit-tested without spawning a subprocess. Keep these pure — they take
+ * the raw string commander hands us and either return the parsed value or
+ * throw with a user-facing message.
+ *
+ * We throw a plain `Error` (with `code = 'commander.invalidArgument'`)
+ * instead of importing `InvalidArgumentError` from commander. Commander's
+ * runtime checks the `code` field, not `instanceof`, so the formatting is
+ * identical — and this keeps the validators trivially unit-testable
+ * without dragging commander's CJS/ESM interop into the test loader.
+ */
+class FlagValidationError extends Error {
+    // Matches commander's own `InvalidArgumentError` so it gets the same
+    // "error: invalid argument for option …" presentation.
+    code = 'commander.invalidArgument';
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidArgumentError';
+    }
+}
+/**
+ * `sync --watch [seconds]`. Bare `-w` (boolean) is short-circuited by
+ * commander before this is invoked; we only see string values here.
+ *
+ * Floor is 2 because the watch loop polls aggressively (every 2s by
+ * default) and faster polling thrashes the manifest endpoint without
+ * measurably improving perceived latency. Ceiling 3600 is a sanity bound
+ * (1h covers any reasonable "slow background sync" use case; users that
+ * want a daily sync should run `magicpixel sync` from cron instead).
+ */
+export function parseWatchInterval(v) {
+    if (typeof v !== 'string')
+        return v;
+    const trimmed = v.trim();
+    const n = parseInt(trimmed, 10);
+    if (!Number.isFinite(n) || String(n) !== trimmed || n < 2 || n > 3600) {
+        throw new FlagValidationError(`expected an integer 2–3600 (seconds), got "${v}".`);
+    }
+    return String(n);
+}
+/** `sync -c <n>` — parallel downloads, 1–16 inclusive. */
+export function parseConcurrency(v) {
+    const n = parseInt(v, 10);
+    if (!Number.isFinite(n) || String(n) !== v.trim() || n < 1 || n > 16) {
+        throw new FlagValidationError(`expected an integer 1–16, got "${v}".`);
+    }
+    return n;
+}

package/dist/util/format.js

@@ -0,0 +1,14 @@
+/**
+ * Human-readable byte formatter shared by `sync` (download summary, progress
+ * bar) and `list` (manifest table). Single source of truth — keep new
+ * call sites pointed here rather than re-implementing locally.
+ */
+export function formatBytes(n) {
+    if (!Number.isFinite(n) || n < 0)
+        return '-';
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}

package/dist/util/framework.js

@@ -54,3 +54,13 @@ export function suggestOutDir(framework, cwd = process.cwd()) {
 export function hasPackageJson(cwd = process.cwd()) {
     return existsSync(resolve(cwd, 'package.json'));
 }
+/**
+ * True when `outDir` lives under `public/` or `static/` — these dirs are
+ * served as-is by frameworks (Next/Astro/Nuxt/CRA/SvelteKit) and cannot be
+ * `import`ed by a bundler. Shared by `init` (skip typed index) and
+ * `emitIndex` (emit absolute-URL AGENTS.md snippet instead of an import).
+ */
+export function isStaticOutDir(outDir) {
+    const norm = outDir.replace(/\\/g, '/').replace(/^\.\//, '');
+    return /^(public|static)(\/|$)/.test(norm);
+}

package/dist/util/iso.js

@@ -0,0 +1,28 @@
+/**
+ * Strict ISO-8601 with required time and timezone (Z or ±HH:MM). Mirrors the
+ * edge function's `ISO_8601_RE` so cursor strings round-trip safely.
+ *
+ * Why strict: the prior `Date.parse`-based check accepted loose inputs like
+ * `"2024/06/01"` which sort lexicographically BEFORE any real ISO string and
+ * would silently rewind `lastSync`, re-downloading history on the next tick.
+ */
+export const STRICT_ISO_8601_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/;
+export function isStrictIso8601(value) {
+    return typeof value === 'string' && STRICT_ISO_8601_RE.test(value);
+}
+/**
+ * Return the lexicographically-greatest valid ISO-8601 timestamp from the
+ * input list, or null if none parse. ISO-8601 strings sort correctly as
+ * strings, so we don't convert to Date (and avoid timezone round-trip drift).
+ * Invalid entries are silently dropped.
+ */
+export function maxIsoTimestamp(values) {
+    let best = null;
+    for (const v of values) {
+        if (!isStrictIso8601(v))
+            continue;
+        if (best === null || v > best)
+            best = v;
+    }
+    return best;
+}

package/dist/util/paths.js

@@ -1,3 +1,5 @@
+import { existsSync } from 'node:fs';
+import { readdir, rm } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { assertPathInsideRoot, assertSafeAssetSegments } from './security.js';
 /**
@@ -27,3 +29,100 @@ function resolveAssetDiskPath(outDir, folder, slug, key, cwd) {
     assertPathInsideRoot(diskPath, base, 'outDir');
     return diskPath;
 }
+/**
+ * Recursively walk `outDir` and return every `*.png` on disk. Skips symlinks
+ * and dot-prefixed directories. Gates every path through `assertPathInsideRoot`
+ * so a symlink/junction outside the tree can't sneak into the result.
+ *
+ * Single canonical disk walker — replaces the two near-identical implementations
+ * that used to live in `sync.ts` (`findLocalPngs`) and `emitIndex.ts`
+ * (`scanDiskAssets`).
+ */
+export async function walkOutDirPngs(outDir, cwd = process.cwd()) {
+    const root = resolve(cwd, outDir);
+    if (!existsSync(root))
+        return [];
+    const out = [];
+    async function walk(dir, folderParts) {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const ent of entries) {
+            if (ent.isSymbolicLink())
+                continue;
+            const full = resolve(dir, ent.name);
+            try {
+                assertPathInsideRoot(full, root, 'outDir');
+            }
+            catch {
+                continue;
+            }
+            if (ent.isDirectory()) {
+                if (ent.name.startsWith('.'))
+                    continue;
+                await walk(full, [...folderParts, ent.name]);
+            }
+            else if (ent.isFile() && ent.name.toLowerCase().endsWith('.png')) {
+                const slug = ent.name.slice(0, -4);
+                const folder = folderParts.length ? folderParts.join('/') : null;
+                const key = folder ? `${folder}/${slug}` : slug;
+                out.push({ abs: full, folder, slug, key });
+            }
+        }
+    }
+    await walk(root, []);
+    return out;
+}
+/**
+ * DFS post-order walk that collects every subdirectory of `root` whose entire
+ * subtree contains no files. Never includes `root` itself. Shared by
+ * `pruneEmptyDirs` (deletes) and `repair --dry-run` (reports).
+ *
+ * Returns directories in post-order so callers that delete sequentially never
+ * try to remove a parent before its children. Soft-fails on per-directory
+ * readdir errors (returns "not empty" so we never delete a directory we
+ * can't actually enumerate).
+ */
+export async function listEmptyDirs(root) {
+    if (!existsSync(root))
+        return [];
+    const out = [];
+    async function walk(d) {
+        let entries;
+        try {
+            entries = await readdir(d, { withFileTypes: true });
+        }
+        catch {
+            return false;
+        }
+        let hasFile = false;
+        let allChildrenEmpty = true;
+        for (const ent of entries) {
+            const full = resolve(d, ent.name);
+            if (ent.isDirectory()) {
+                const childEmpty = await walk(full);
+                if (childEmpty)
+                    out.push(full);
+                else
+                    allChildrenEmpty = false;
+            }
+            else {
+                hasFile = true;
+            }
+        }
+        return !hasFile && allChildrenEmpty;
+    }
+    await walk(root);
+    return out;
+}
+/**
+ * Recursively delete empty subdirectories under `root`. Never removes `root`
+ * itself. Idempotent and safe to call after every prune pass.
+ */
+export async function pruneEmptyDirs(root) {
+    const empties = await listEmptyDirs(root);
+    // `listEmptyDirs` returns post-order, so deleting sequentially never tries
+    // to remove a parent before its children. `force: true` swallows the rare
+    // race where a sibling pass already removed the directory.
+    for (const p of empties) {
+        await rm(p, { recursive: true, force: true });
+    }
+}

package/dist/util/security.js

@@ -44,6 +44,13 @@ export function validateEndpointUrl(raw) {
         throw new Error(`endpoint is not a valid URL: ${raw}\n` +
             `  Fix: use https://… or remove "endpoint" from magicpixel.json.`);
     }
+    // Explicit allowlist of schemes. Anything outside { https, http } —
+    // file:, data:, javascript:, ws:, gopher:, etc. — is rejected up-front
+    // with a clearer message than the generic HTTPS error.
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+        throw new Error(`endpoint scheme "${url.protocol}" is not allowed.\n` +
+            `  Fix: use an https:// URL (http://localhost is allowed with MAGICPIXEL_ALLOW_INSECURE_ENDPOINT=1).`);
+    }
     if (url.username || url.password) {
         throw new Error(`endpoint must not embed credentials in the URL.\n` +
             `  Fix: use MAGICPIXEL_API_KEY for auth, not user:pass@host.`);
@@ -52,7 +59,10 @@ export function validateEndpointUrl(raw) {
         return normalizeEndpointBase(url);
     }
     const allowInsecure = process.env.MAGICPIXEL_ALLOW_INSECURE_ENDPOINT === '1';
-    if (allowInsecure && url.protocol === 'http:' && (url.hostname === 'localhost' || url.hostname === '127.0.0.1')) {
+    if (allowInsecure && url.hostname === 'localhost') {
+        return normalizeEndpointBase(url);
+    }
+    if (allowInsecure && url.hostname === '127.0.0.1') {
         return normalizeEndpointBase(url);
     }
     throw new Error(`endpoint must use HTTPS (${url.protocol}//${url.host}).\n` +
@@ -116,7 +126,8 @@ export async function readBodyWithLimit(res, maxBytes) {
     }
     return buf;
 }
-const MAX_GLOB_LEN = 256;
+/** Max length of a user-supplied picomatch glob; shared with config.ts. */
+export const MAX_GLOB_LEN = 256;
 /** Validate a user-supplied picomatch glob from the CLI. */
 export function assertSafeGlob(glob) {
     const g = glob.trim();
@@ -125,3 +136,29 @@ export function assertSafeGlob(glob) {
     }
     return g;
 }
+/**
+ * Trim + validate a candidate `outDir`. Single source of truth shared by
+ * `init` (prompt-time) and `loadConfig` (file-time) so a path that survives
+ * one is guaranteed to survive the other.
+ *
+ * Returns the trimmed value. Throws on:
+ *   - empty / whitespace-only input
+ *   - any `..` segment or null byte
+ *   - absolute paths — otherwise an outDir like `/tmp/mp` would resolve to
+ *     itself and bypass the cwd-relative containment check in
+ *     `assertPathInsideRoot`, letting a manifest write outside the project
+ *     tree. `outDir` must always be relative to the project root.
+ */
+export function assertSafeOutDir(value) {
+    const v = value.trim();
+    if (!v) {
+        throw new Error('outDir must not be empty.');
+    }
+    if (v.includes('\0') || v.split(/[/\\]/).some((seg) => seg === '..')) {
+        throw new Error('outDir must not contain ".." segments or null bytes.');
+    }
+    if (isAbsolute(v)) {
+        throw new Error('outDir must be a relative path (not absolute).');
+    }
+    return v;
+}