@magicpixelart/cli 0.1.0 → 0.1.2

package/README.md

@@ -1,13 +1,13 @@
-# @magicpixel/cli
+# @magicpixelart/cli
 
 Sync MagicPixel pixel-art assets to your local project as flattened PNGs. Zero runtime — just files on disk that your bundler picks up.
 
 ## Install
 
 ```bash
-npm install --save-dev @magicpixel/cli
-# or: pnpm add -D @magicpixel/cli
-# or: bun add -d @magicpixel/cli
+npm install --save-dev @magicpixelart/cli
+# or: pnpm add -D @magicpixelart/cli
+# or: bun add -d @magicpixelart/cli
 ```
 
 Requires Node.js ≥ 18.
@@ -21,7 +21,9 @@ npx magicpixel sync          # downloads changed assets
 npx magicpixel sync --watch  # keeps assets fresh while you work
 ```
 
-Get an API key at [magicpixel.art/settings](https://magicpixel.art/settings) → API Keys. Each key is bound to one project.
+Get an API key at [magicpixel.art/settings](https://magicpixel.art/settings) → API Keys. Each key is bound to one project. Production keys are prefixed `mp_live_`; sandbox keys (used internally for tests) are prefixed `mp_test_` and accepted the same way.
+
+The key is read **only** from the `MAGICPIXEL_API_KEY` environment variable — never from `magicpixel.json` or any other file. This is intentional: it keeps secrets out of repos and CI logs.
 
 ## Typed asset index (default on)
 
@@ -74,9 +76,13 @@ Sync is built to be cheap: a no-op run is one small manifest request, zero PNG b
 | `include`  | `string[]` | `["**/*"]`              | Globs (picomatch) matched against `folder/slug`. |
 | `exclude`  | `string[]` | `[]`                    | Globs to exclude.                                |
 | `emitIndex`| `boolean`  | `true`                  | Emit `<outDir>/index.ts` with typed asset map.   |
-| `endpoint` | `string?`  | production URL          | Override the API base (testing only).            |
+| `endpoint` | `string?`  | production URL          | Override the API base (testing only). Must be **HTTPS**. |
+
+State (`.magicpixel/state.json`) tracks `lastSync` (file mode `0600`). Add `.magicpixel/` to `.gitignore` (init offers to do this).
+
+### Custom endpoint (advanced)
 
-State (`.magicpixel/state.json`) tracks `lastSync`. Add `.magicpixel/` to `.gitignore` (init offers to do this).
+For local integration testing against `http://localhost`, set `MAGICPIXEL_ALLOW_INSECURE_ENDPOINT=1` in the environment. Do not commit custom endpoints to shared repos — `sync` warns when `endpoint` is set.
 
 ## CI usage
 
@@ -93,7 +99,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with: { node-version: 20 }
-      - run: npx -y @magicpixel/cli sync --prune --quiet
+      - run: npx -y @magicpixelart/cli sync --prune --quiet
         env:
           MAGICPIXEL_API_KEY: ${{ secrets.MAGICPIXEL_API_KEY }}
       - uses: peter-evans/create-pull-request@v6

package/dist/api.js

@@ -1,4 +1,5 @@
 import { resolveEndpoint, getApiKey, CLI_USER_AGENT } from './config.js';
+import { etagForSha256, MAX_ASSET_BYTES, readBodyWithLimit, safeFetch, } from './util/security.js';
 export class ApiError extends Error {
     status;
     constructor(status, message) {
@@ -43,7 +44,7 @@ export async function fetchManifestPage(opts) {
         url.searchParams.set('limit', String(opts.limit));
     let res;
     try {
-        res = await fetch(url, { headers: authHeaders() });
+        res = await safeFetch(url.href, { headers: authHeaders() });
     }
     catch (e) {
         throw new Error(`manifest: network error (${e.message}).\n` +
@@ -57,12 +58,18 @@ export async function fetchManifestPage(opts) {
 export async function fetchAllManifest(config, since) {
     const out = [];
     let cursor;
-    do {
-        const page = await fetchManifestPage({ config, since, cursor, limit: 500 });
-        out.push(...page.items);
-        cursor = page.nextCursor ?? undefined;
-    } while (cursor);
-    return out;
+    // Cycle guard: caps total pages so a buggy server cursor can't hang the CLI.
+    // At 500 entries/page this is 100k assets — well past any realistic project.
+    const MAX_PAGES = 200;
+    for (let page = 0; page < MAX_PAGES; page++) {
+        const res = await fetchManifestPage({ config, since, cursor, limit: 500 });
+        out.push(...res.items);
+        cursor = res.nextCursor ?? undefined;
+        if (!cursor)
+            return out;
+    }
+    throw new Error(`manifest: pagination exceeded ${MAX_PAGES} pages — possible server cursor loop.\n` +
+        `  Fix: re-run with --full, or report at https://github.com/magicpixel/cli/issues.`);
 }
 /**
  * Download a single asset by key. Returns null on 304 (not modified).
@@ -73,21 +80,27 @@ export async function fetchAssetBytes(config, key, knownSha) {
     url.searchParams.set('key', key);
     const headers = authHeaders();
     if (knownSha)
-        headers['If-None-Match'] = `"${knownSha}"`;
+        headers['If-None-Match'] = etagForSha256(knownSha);
     const maxAttempts = 3;
     let lastErr = null;
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
         try {
-            const res = await fetch(url, { headers });
-            if (res.status === 304)
+            const res = await safeFetch(url.href, { headers });
+            if (res.status === 304) {
+                // Drain so undici can return the socket to the keep-alive pool.
+                await res.body?.cancel();
                 return null;
+            }
             if (res.ok)
-                return new Uint8Array(await res.arrayBuffer());
+                return await readBodyWithLimit(res, MAX_ASSET_BYTES);
+            // Consume the body via .text() for the error message; this also drains
+            // the stream so we don't leak the socket on retry.
+            const bodyText = await res.text();
             if (res.status === 429 || res.status >= 500) {
-                lastErr = new ApiError(res.status, friendly(res.status, await res.text(), `download ${key}`));
+                lastErr = new ApiError(res.status, friendly(res.status, bodyText, `download ${key}`));
             }
             else {
-                throw new ApiError(res.status, friendly(res.status, await res.text(), `download ${key}`));
+                throw new ApiError(res.status, friendly(res.status, bodyText, `download ${key}`));
             }
         }
         catch (e) {

package/dist/commands/add.js

@@ -1,12 +1,14 @@
 import kleur from 'kleur';
 import { loadConfig, saveConfig } from '../config.js';
+import { assertSafeGlob } from '../util/security.js';
 export async function addCommand(glob) {
+    const pattern = assertSafeGlob(glob);
     const config = await loadConfig();
-    if (config.include.includes(glob)) {
-        console.log(kleur.yellow(`already included: ${glob}`));
+    if (config.include.includes(pattern)) {
+        console.log(kleur.yellow(`already included: ${pattern}`));
         return;
     }
-    config.include.push(glob);
+    config.include.push(pattern);
     await saveConfig(config);
-    console.log(kleur.green(`✓ added include pattern: ${glob}`));
+    console.log(kleur.green(`✓ added include pattern: ${pattern}`));
 }

package/dist/commands/init.js

@@ -20,7 +20,7 @@ export async function initCommand(opts) {
     if (interactive) {
         const rl = createInterface({ input: stdin, output: stdout });
         try {
-            console.log(kleur.bold('Set up @magicpixel/cli'));
+            console.log(kleur.bold('Set up @magicpixelart/cli'));
             if (framework)
                 console.log(kleur.dim(`  Detected: ${framework}`));
             console.log();
@@ -115,9 +115,11 @@ function isImportableOutDir(outDir) {
 async function ensureGitignore() {
     const path = resolve(process.cwd(), '.gitignore');
     const marker = '.magicpixel/';
+    // Accept any of these as "already ignored" so we don't append a duplicate.
+    const equivalents = new Set(['.magicpixel', '.magicpixel/', '/.magicpixel', '/.magicpixel/']);
     if (existsSync(path)) {
         const current = await readFile(path, 'utf8');
-        if (current.split('\n').some((l) => l.trim() === marker))
+        if (current.split('\n').some((l) => equivalents.has(l.trim())))
             return false;
         await appendFile(path, (current.endsWith('\n') ? '' : '\n') + `\n# MagicPixel CLI state\n${marker}\n`);
         return true;

package/dist/commands/remove.js

@@ -1,13 +1,15 @@
 import kleur from 'kleur';
 import { loadConfig, saveConfig } from '../config.js';
+import { assertSafeGlob } from '../util/security.js';
 export async function removeCommand(glob) {
+    const pattern = assertSafeGlob(glob);
     const config = await loadConfig();
     const before = config.include.length;
-    config.include = config.include.filter((g) => g !== glob);
+    config.include = config.include.filter((g) => g !== pattern);
     if (config.include.length === before) {
-        console.log(kleur.yellow(`not found in include: ${glob}`));
+        console.log(kleur.yellow(`not found in include: ${pattern}`));
         return;
     }
     await saveConfig(config);
-    console.log(kleur.green(`✓ removed include pattern: ${glob}`));
+    console.log(kleur.green(`✓ removed include pattern: ${pattern}`));
 }

package/dist/commands/sync.js

@@ -1,5 +1,6 @@
 import kleur from 'kleur';
 import ora from 'ora';
+import { createHash } from 'node:crypto';
 import { mkdir, writeFile, unlink, readdir, rm, rename } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { dirname, relative, resolve } from 'node:path';
@@ -9,6 +10,7 @@ import { fileSha256 } from '../util/hash.js';
 import { assetDiskPath } from '../util/paths.js';
 import { createLimit } from '../util/limit.js';
 import { emitTypedIndex } from '../util/emitIndex.js';
+import { assertPathInsideRoot, tmpPathFor } from '../util/security.js';
 export async function syncCommand(opts) {
     if (opts.watch) {
         await watchLoop(opts);
@@ -19,16 +21,34 @@ export async function syncCommand(opts) {
 async function watchLoop(opts) {
     const intervalSec = typeof opts.watch === 'string' ? Math.max(2, parseInt(opts.watch, 10) || 10) : 10;
     console.log(kleur.dim(`[watch] polling every ${intervalSec}s. Ctrl+C to stop.`));
-    // Run once eagerly so first sync isn't delayed by the interval.
+    let stopping = false;
     let inFlight = false;
+    let resolveIdle = null;
+    const onSigint = () => {
+        if (stopping)
+            return;
+        stopping = true;
+        process.stdout.write('\x1b[2K\r');
+        if (inFlight) {
+            // Let the current sync drain so we don't leave half-written *.tmp files
+            // or an unflushed lastSync state. Second Ctrl+C hard-exits.
+            console.log(kleur.dim('[watch] finishing current sync… (Ctrl+C again to force quit)'));
+            process.once('SIGINT', () => process.exit(130));
+        }
+        else {
+            console.log(kleur.dim('[watch] stopped.'));
+            process.exit(0);
+        }
+    };
+    process.on('SIGINT', onSigint);
+    // Run once eagerly so first sync isn't delayed by the interval.
     const tick = async () => {
-        if (inFlight)
+        if (inFlight || stopping)
             return;
         inFlight = true;
         try {
             const r = await runOnce({ ...opts, quiet: true, watch: false });
             if (r.downloaded > 0 || r.pruned > 0) {
-                // \x1b[2K\r clears any residual "no changes" line from the previous tick.
                 process.stdout.write('\x1b[2K\r');
                 console.log(`${kleur.dim(timestamp())} ${kleur.green('✓')} ${r.downloaded} downloaded` +
                     (r.pruned ? `, ${r.pruned} pruned` : '') +
@@ -43,14 +63,25 @@ async function watchLoop(opts) {
         }
         finally {
             inFlight = false;
+            resolveIdle?.();
+            resolveIdle = null;
         }
     };
     await tick();
-    // eslint-disable-next-line no-constant-condition
-    while (true) {
+    while (!stopping) {
         await new Promise((r) => setTimeout(r, intervalSec * 1000));
+        if (stopping)
+            break;
         await tick();
     }
+    // SIGINT arrived mid-tick — wait for it to drain, then exit cleanly.
+    if (inFlight) {
+        await new Promise((r) => {
+            resolveIdle = r;
+        });
+    }
+    console.log(kleur.dim('[watch] stopped.'));
+    process.exit(0);
 }
 async function runOnce(opts) {
     const config = await loadConfig();
@@ -58,6 +89,11 @@ async function runOnce(opts) {
     const startedAt = new Date().toISOString();
     const concurrency = Math.max(1, Math.min(opts.concurrency ?? 6, 16));
     const quiet = !!opts.quiet;
+    // Warn loudly when a custom endpoint is configured — easy to forget a test
+    // override before committing magicpixel.json to a real repo / CI.
+    if (!quiet && config.endpoint) {
+        console.log(kleur.yellow(`! using custom endpoint: ${config.endpoint}`));
+    }
     // Incremental: only fetch what changed since last successful sync.
     // --full forces a from-scratch fetch.
     const since = opts.full ? undefined : state.lastSync;
@@ -142,8 +178,17 @@ async function runOnce(opts) {
                 result.unchanged++;
             }
             else {
+                // Verify the payload matches what the manifest advertised. Guards
+                // against silently writing a corrupted body to disk.
+                if (entry.sha256) {
+                    const actual = createHash('sha256').update(bytes).digest('hex');
+                    if (actual !== entry.sha256) {
+                        throw new Error(`sha256 mismatch (expected ${entry.sha256.slice(0, 12)}…, got ${actual.slice(0, 12)}…)`);
+                    }
+                }
                 await mkdir(dirname(diskPath), { recursive: true });
-                const tmp = `${diskPath}.${process.pid}.tmp`;
+                const tmp = tmpPathFor(diskPath);
+                assertPathInsideRoot(tmp, resolve(process.cwd(), config.outDir), 'outDir');
                 await writeFile(tmp, bytes);
                 await rename(tmp, diskPath);
                 result.downloaded++;
@@ -170,7 +215,9 @@ async function runOnce(opts) {
     }
     // Prune
     if (opts.prune && orphans.length > 0) {
+        const outRoot = resolve(process.cwd(), config.outDir);
         for (const p of orphans) {
+            assertPathInsideRoot(p, outRoot, 'outDir');
             await unlink(p);
             if (!quiet)
                 console.log(`  ${kleur.red('-')} ${relative(process.cwd(), p)}`);
@@ -251,11 +298,20 @@ function printOrphans(orphans) {
 async function findLocalPngs(dir) {
     if (!existsSync(dir))
         return [];
+    const root = resolve(dir);
     const out = [];
     async function walk(d) {
         const entries = await readdir(d, { withFileTypes: true });
         for (const ent of entries) {
+            if (ent.isSymbolicLink())
+                continue;
             const full = resolve(d, ent.name);
+            try {
+                assertPathInsideRoot(full, root, 'outDir');
+            }
+            catch {
+                continue;
+            }
             if (ent.isDirectory()) {
                 await walk(full);
             }
@@ -264,7 +320,7 @@ async function findLocalPngs(dir) {
             }
         }
     }
-    await walk(dir);
+    await walk(root);
     return out;
 }
 async function pruneEmptyDirs(root) {

package/dist/commands/whoami.js

@@ -1,25 +1,38 @@
 import kleur from 'kleur';
 import { loadConfig, resolveEndpoint, getApiKey } from '../config.js';
+import { CLI_USER_AGENT } from '../version.js';
+import { safeFetch } from '../util/security.js';
 export async function whoamiCommand() {
     const config = await loadConfig();
+    // Ask for a full page (server caps at 1000) so `count` is honest for any
+    // project with ≤1000 assets — the previous `limit=1` always reported "1+".
     const url = new URL(`${resolveEndpoint(config)}/manifest`);
-    url.searchParams.set('limit', '1');
-    const res = await fetch(url, {
-        headers: { Authorization: `Bearer ${getApiKey()}` },
+    url.searchParams.set('limit', '1000');
+    const res = await safeFetch(url.href, {
+        headers: { Authorization: `Bearer ${getApiKey()}`, 'User-Agent': CLI_USER_AGENT },
     });
     if (res.status === 401 || res.status === 403) {
+        await res.body?.cancel();
         console.log(kleur.red('✗ API key rejected (401/403).'));
         console.log(kleur.dim('  Generate a new key at MagicPixel → Settings → API Keys.'));
         process.exitCode = 1;
         return;
     }
     if (!res.ok) {
-        console.log(kleur.red(`✗ ${res.status}: ${await res.text()}`));
+        const body = await res.text();
+        console.log(kleur.red(`✗ ${res.status}: ${body.slice(0, 200)}`));
         process.exitCode = 1;
         return;
     }
     const body = (await res.json());
+    const more = body.nextCursor ? '+' : '';
     console.log(kleur.green('✓ key valid'));
     console.log(`  endpoint: ${resolveEndpoint(config)}`);
-    console.log(`  visible:  ${body.count > 0 ? `${body.count}+ asset${body.count === 1 ? '' : 's'} (first: ${body.items[0]?.key ?? '-'})` : kleur.yellow('0 assets — is the key bound to a project with content?')}`);
+    if (body.count === 0) {
+        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 ?? '-'})`);
+    }
 }

package/dist/config.js

@@ -1,6 +1,7 @@
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
+import { validateEndpointUrl } from './util/security.js';
 const CONFIG_FILENAME = 'magicpixel.json';
 const STATE_DIR = '.magicpixel';
 const STATE_FILENAME = 'state.json';
@@ -32,14 +33,50 @@ export async function loadConfig(cwd = process.cwd()) {
         throw new Error(`${CONFIG_FILENAME} is not valid JSON: ${e.message}\n` +
             `  Fix: open the file and check for trailing commas or quotes.`);
     }
+    const include = normalizeGlobList(parsed.include ?? defaultConfig.include, 'include');
+    const exclude = normalizeGlobList(parsed.exclude ?? defaultConfig.exclude, 'exclude');
+    const outDir = typeof parsed.outDir === 'string' && parsed.outDir.trim() ? parsed.outDir.trim() : defaultConfig.outDir;
+    if (outDir.includes('\0') || outDir.split(/[/\\]/).some((seg) => seg === '..')) {
+        throw new Error(`${CONFIG_FILENAME}: outDir must not contain ".." segments.\n` +
+            `  Fix: use a path like src/assets/magicpixel.`);
+    }
+    let endpoint;
+    if (parsed.endpoint !== undefined) {
+        if (typeof parsed.endpoint !== 'string' || !parsed.endpoint.trim()) {
+            throw new Error(`${CONFIG_FILENAME}: "endpoint" must be a non-empty string.\n  Fix: remove the field to use the default API.`);
+        }
+        endpoint = validateEndpointUrl(parsed.endpoint.trim());
+    }
     return {
-        outDir: parsed.outDir ?? defaultConfig.outDir,
-        include: parsed.include ?? defaultConfig.include,
-        exclude: parsed.exclude ?? defaultConfig.exclude,
-        endpoint: parsed.endpoint,
+        outDir,
+        include,
+        exclude,
+        endpoint,
         emitIndex: parsed.emitIndex ?? defaultConfig.emitIndex,
     };
 }
+const MAX_GLOBS = 64;
+const MAX_GLOB_LEN = 256;
+function normalizeGlobList(value, field) {
+    if (!Array.isArray(value)) {
+        throw new Error(`${CONFIG_FILENAME}: "${field}" must be an array of glob strings.`);
+    }
+    if (value.length > MAX_GLOBS) {
+        throw new Error(`${CONFIG_FILENAME}: "${field}" has too many entries (max ${MAX_GLOBS}).`);
+    }
+    const out = [];
+    for (const item of value) {
+        if (typeof item !== 'string' || !item.trim()) {
+            throw new Error(`${CONFIG_FILENAME}: "${field}" entries must be non-empty strings.`);
+        }
+        const g = item.trim();
+        if (g.length > MAX_GLOB_LEN || g.includes('\0')) {
+            throw new Error(`${CONFIG_FILENAME}: "${field}" entry is too long or invalid.`);
+        }
+        out.push(g);
+    }
+    return out;
+}
 export async function saveConfig(config, cwd = process.cwd()) {
     await writeFile(configPath(cwd), JSON.stringify(config, null, 2) + '\n', 'utf8');
 }
@@ -57,10 +94,12 @@ export async function loadState(cwd = process.cwd()) {
 export async function saveState(state, cwd = process.cwd()) {
     const path = statePath(cwd);
     await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, JSON.stringify(state, null, 2) + '\n', 'utf8');
+    await writeFile(path, JSON.stringify(state, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
 }
 export function resolveEndpoint(config) {
-    return config.endpoint ?? DEFAULT_ENDPOINT;
+    if (config.endpoint)
+        return config.endpoint;
+    return DEFAULT_ENDPOINT;
 }
 export function getApiKey() {
     const key = process.env.MAGICPIXEL_API_KEY;
@@ -71,10 +110,15 @@ export function getApiKey() {
             '    2. export MAGICPIXEL_API_KEY=mp_live_...\n' +
             '    3. Re-run the command.');
     }
-    if (!/^mp_(live|test)_/.test(key)) {
-        throw new Error(`MAGICPIXEL_API_KEY does not look right (expected to start with "mp_live_").\n` +
+    const trimmed = key.trim();
+    if (trimmed !== key) {
+        throw new Error(`MAGICPIXEL_API_KEY has leading/trailing whitespace.\n` +
+            `  Fix: export the key without spaces or quotes.`);
+    }
+    if (!/^mp_(live|test)_[a-f0-9]{64}$/.test(trimmed)) {
+        throw new Error(`MAGICPIXEL_API_KEY does not look right (expected mp_live_… or mp_test_…).\n` +
             `  Fix: re-copy the key from https://magicpixel.art/settings.`);
     }
-    return key;
+    return trimmed;
 }
-export const CLI_USER_AGENT = `@magicpixel/cli/0.1.0 (node ${process.versions.node})`;
+export { CLI_USER_AGENT, CLI_VERSION } from './version.js';

package/dist/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { Command } from 'commander';
+import { Command, InvalidArgumentError } from 'commander';
 import kleur from 'kleur';
 import { initCommand } from './commands/init.js';
 import { syncCommand } from './commands/sync.js';
@@ -8,6 +8,7 @@ import { removeCommand } from './commands/remove.js';
 import { listCommand } from './commands/list.js';
 import { statusCommand } from './commands/status.js';
 import { whoamiCommand } from './commands/whoami.js';
+import { CLI_VERSION } from './version.js';
 // Node version guard
 const major = Number(process.versions.node.split('.')[0]);
 if (major < 18) {
@@ -18,7 +19,7 @@ const program = new Command();
 program
     .name('magicpixel')
     .description('Sync MagicPixel pixel-art assets to your local project')
-    .version('0.1.0');
+    .version(CLI_VERSION);
 const wrap = (fn) => async (...args) => {
     try {
         await fn(...args);
@@ -44,7 +45,13 @@ program
     .option('--full', 'Ignore lastSync state; re-fetch the full manifest')
     .option('-w, --watch [seconds]', 'Poll for changes (default 10s)', (v) => v ?? true)
     .option('-q, --quiet', 'Minimal output (for CI)')
-    .option('-c, --concurrency <n>', 'Parallel downloads (1–16, default 6)', (v) => parseInt(v, 10))
+    .option('-c, --concurrency <n>', 'Parallel downloads (1–16, default 6)', (v) => {
+    const n = parseInt(v, 10);
+    if (!Number.isFinite(n) || String(n) !== v.trim() || n < 1 || n > 16) {
+        throw new InvalidArgumentError(`expected an integer 1–16, got "${v}".`);
+    }
+    return n;
+})
     .action(wrap(async (opts) => syncCommand(opts)));
 program
     .command('add <glob>')

package/dist/util/emitIndex.js

@@ -1,5 +1,7 @@
-import { writeFile } from 'node:fs/promises';
+import { readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { assertSafeAssetSegments } from './security.js';
 /**
  * Emit `<outDir>/index.ts` with a typed map of every asset key → URL.
  *
@@ -10,30 +12,55 @@ import { resolve } from 'node:path';
  * time. No runtime, no bundler config.
  */
 export async function emitTypedIndex(outDir, manifest, cwd = process.cwd()) {
-    const sorted = [...manifest].sort((a, b) => a.key.localeCompare(b.key));
+    // Dedupe by key. A well-behaved manifest never has duplicates, but a server
+    // bug here would otherwise emit duplicate object keys and break TS compile.
+    const seen = new Set();
+    const sorted = [...manifest]
+        .sort((a, b) => a.key.localeCompare(b.key))
+        .filter((e) => {
+        if (seen.has(e.key)) {
+            console.warn(`magicpixel: duplicate manifest key "${e.key}" — keeping first.`);
+            return false;
+        }
+        seen.add(e.key);
+        return true;
+    });
     const lines = [
-        '// AUTOGENERATED by @magicpixel/cli. Do not edit.',
+        '// AUTOGENERATED by @magicpixelart/cli. Do not edit.',
         '// Re-runs of `magicpixel sync` overwrite this file.',
         '',
     ];
-    for (const e of sorted) {
+    // Use positional identifiers (asset_0, asset_1, …) so keys that differ only
+    // by non-alphanumeric chars (e.g. `player/walk` vs `player_walk`) can't
+    // collide on the JS identifier and break the consumer's TS build.
+    sorted.forEach((e, i) => {
+        assertSafeAssetSegments(e.folder, e.slug, e.key);
         const rel = e.folder ? `./${e.folder}/${e.slug}.png` : `./${e.slug}.png`;
-        const safe = JSON.stringify(rel);
-        lines.push(`import asset_${slugToIdent(e.key)} from ${safe};`);
-    }
+        lines.push(`import asset_${i} from ${JSON.stringify(rel)};`);
+    });
     lines.push('');
     lines.push('export const MagicPixelAssets = {');
-    for (const e of sorted) {
-        lines.push(`  ${JSON.stringify(e.key)}: asset_${slugToIdent(e.key)},`);
-    }
+    sorted.forEach((e, i) => {
+        lines.push(`  ${JSON.stringify(e.key)}: asset_${i},`);
+    });
     lines.push('} as const;');
     lines.push('');
     lines.push('export type MagicPixelAssetKey = keyof typeof MagicPixelAssets;');
     lines.push('');
     const path = resolve(cwd, outDir, 'index.ts');
-    await writeFile(path, lines.join('\n'), 'utf8');
+    const next = lines.join('\n');
+    // Skip the write when contents are identical. Avoids triggering Vite/webpack
+    // HMR reloads on every `--watch` poll when nothing actually changed.
+    if (existsSync(path)) {
+        try {
+            const current = await readFile(path, 'utf8');
+            if (current === next)
+                return path;
+        }
+        catch {
+            // fall through and overwrite
+        }
+    }
+    await writeFile(path, next, 'utf8');
     return path;
 }
-function slugToIdent(key) {
-    return key.replace(/[^a-zA-Z0-9]/g, '_');
-}

package/dist/util/paths.js

@@ -1,11 +1,15 @@
 import { resolve } from 'node:path';
+import { assertPathInsideRoot, assertSafeAssetSegments } from './security.js';
 /**
  * Disk path for a manifest entry under `outDir`. Mirrors the MagicPixel
  * folder structure: `outDir/<folder>/<slug>.png`. Unsorted assets land at
  * `outDir/<slug>.png`.
  */
 export function assetDiskPath(outDir, entry, cwd = process.cwd()) {
+    assertSafeAssetSegments(entry.folder, entry.slug, entry.key);
     const base = resolve(cwd, outDir);
     const file = `${entry.slug}.png`;
-    return entry.folder ? resolve(base, entry.folder, file) : resolve(base, file);
+    const diskPath = entry.folder ? resolve(base, entry.folder, file) : resolve(base, file);
+    assertPathInsideRoot(diskPath, base, 'outDir');
+    return diskPath;
 }

package/dist/util/security.js

@@ -0,0 +1,127 @@
+import { randomBytes } from 'node:crypto';
+import { 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;
+/**
+ * Resolved path must stay under `rootDir` (prevents manifest-driven path traversal).
+ */
+export function assertPathInsideRoot(targetPath, rootDir, label) {
+    const root = resolve(rootDir);
+    const target = resolve(targetPath);
+    const rel = relative(root, target);
+    if (rel === '' || (!rel.startsWith('..') && !isAbsolute(rel)))
+        return;
+    throw new Error(`refusing to write outside ${label} (${relative(process.cwd(), root) || '.'}).\n` +
+        `  Fix: report unexpected folder/slug values to MagicPixel support.`);
+}
+/**
+ * Reject manifest folder/slug values that could escape via `..` or separators.
+ */
+export function assertSafeAssetSegments(folder, slug, key) {
+    const badSegment = (seg) => seg.length === 0 || seg === '.' || seg === '..' || /[\0\\]/.test(seg);
+    if (badSegment(slug)) {
+        throw new Error(`unsafe asset slug in manifest for key "${key}".`);
+    }
+    if (folder !== null) {
+        for (const seg of folder.split('/')) {
+            if (badSegment(seg)) {
+                throw new Error(`unsafe asset folder in manifest for key "${key}".`);
+            }
+        }
+    }
+}
+/**
+ * Custom endpoints must be HTTPS (unless MAGICPIXEL_ALLOW_INSECURE_ENDPOINT=1 for local http).
+ * Credentials embedded in the URL are rejected.
+ */
+export function validateEndpointUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`endpoint is not a valid URL: ${raw}\n` +
+            `  Fix: use https://… or remove "endpoint" from magicpixel.json.`);
+    }
+    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.`);
+    }
+    if (url.protocol === 'https:') {
+        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')) {
+        return normalizeEndpointBase(url);
+    }
+    throw new Error(`endpoint must use HTTPS (${url.protocol}//${url.host}).\n` +
+        `  Fix: remove "endpoint" to use production, or for local http://localhost set ` +
+        `MAGICPIXEL_ALLOW_INSECURE_ENDPOINT=1.`);
+}
+function normalizeEndpointBase(url) {
+    // Drop query/hash; trim trailing slash on pathname (except root).
+    const path = url.pathname.replace(/\/+$/, '') || '';
+    return `${url.protocol}//${url.host}${path}`;
+}
+export function isSha256Hex(value) {
+    return SHA256_RE.test(value);
+}
+export function etagForSha256(sha256) {
+    if (!isSha256Hex(sha256)) {
+        throw new Error('internal: refusing to send If-None-Match for non-sha256 value');
+    }
+    return `"${sha256.toLowerCase()}"`;
+}
+export function tmpPathFor(diskPath) {
+    const suffix = randomBytes(8).toString('hex');
+    return `${diskPath}.${process.pid}.${suffix}.tmp`;
+}
+/**
+ * Follow redirects only within the same origin as the initial request (prevents API key leak).
+ */
+export async function safeFetch(url, init = {}) {
+    const origin = new URL(url).origin;
+    let current = url;
+    for (let hop = 0; hop < 5; hop++) {
+        const res = await fetch(current, { ...init, redirect: 'manual' });
+        if (res.status < 300 || res.status >= 400)
+            return res;
+        const location = res.headers.get('location');
+        await res.body?.cancel();
+        if (!location) {
+            throw new Error(`HTTP ${res.status} redirect without Location header.`);
+        }
+        const next = new URL(location, current);
+        if (next.origin !== origin) {
+            throw new Error(`refusing cross-origin redirect to ${next.origin}.\n` +
+                `  Fix: point "endpoint" directly at the integration API; do not use redirecting URLs.`);
+        }
+        current = next.href;
+    }
+    throw new Error('too many HTTP redirects (max 5).');
+}
+export async function readBodyWithLimit(res, maxBytes) {
+    const declared = res.headers.get('content-length');
+    if (declared) {
+        const n = Number(declared);
+        if (Number.isFinite(n) && n > maxBytes) {
+            await res.body?.cancel();
+            throw new Error(`response too large (${n} bytes, max ${maxBytes}).`);
+        }
+    }
+    const buf = new Uint8Array(await res.arrayBuffer());
+    if (buf.byteLength > maxBytes) {
+        throw new Error(`response too large (${buf.byteLength} bytes, max ${maxBytes}).`);
+    }
+    return buf;
+}
+const MAX_GLOB_LEN = 256;
+/** 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).`);
+    }
+    return g;
+}

package/dist/version.js

@@ -0,0 +1,8 @@
+import { createRequire } from 'node:module';
+// Single source of truth: read version from package.json at runtime so
+// `npm version <bump>` propagates everywhere without code edits.
+// dist/version.js resolves `../package.json` → tools/cli/package.json.
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+export const CLI_VERSION = pkg.version;
+export const CLI_USER_AGENT = `@magicpixelart/cli/${CLI_VERSION} (node ${process.versions.node})`;

package/package.json

@@ -1,16 +1,12 @@
 {
   "name": "@magicpixelart/cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Sync MagicPixel pixel-art assets to your local project.",
   "type": "module",
   "bin": {
     "magicpixel": "dist/index.js"
   },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
+  "files": ["dist", "README.md", "LICENSE"],
   "scripts": {
     "build": "tsc && node -e \"require('fs').chmodSync('dist/index.js', 0o755)\"",
     "dev": "tsx src/index.ts",
@@ -30,7 +26,7 @@
     "url": "git+https://github.com/handpoke/magicpixel-cli.git"
   },
   "bugs": {
-    "url": "https://github.com/magicpixel/cli/issues"
+    "url": "https://github.com/handpoke/magicpixel-cli/issues"
   },
   "license": "MIT",
   "author": "MagicPixel",