@magicpixelart/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MagicPixel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# @magicpixel/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
+```
+
+Requires Node.js ≥ 18.
+
+## Quickstart
+
+```bash
+npx magicpixel init          # interactive setup, detects your framework
+export MAGICPIXEL_API_KEY=mp_live_...
+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.
+
+## Typed asset index (default on)
+
+If `emitIndex` is true in `magicpixel.json`, every sync writes `<outDir>/index.ts`:
+
+```ts
+import { MagicPixelAssets, type MagicPixelAssetKey } from '@/assets/magicpixel';
+
+<img src={MagicPixelAssets['player/walk']} />
+// Typo? TypeScript error. Vite/webpack hash the URL at build time.
+```
+
+No bundler config, no runtime, no extra package.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `init [-y] [--force]` | Interactive config wizard. `-y` for CI. |
+| `sync [...flags]` | Fetch manifest, diff against disk, download changed assets. |
+| `add <glob>` / `remove <glob>` | Manage `include` patterns. |
+| `list` | Print matching manifest as a table. |
+| `status` | Config, last sync, diff vs remote. |
+| `whoami` | Verify API key, report visible assets. |
+
+### `sync` flags
+
+| Flag | Meaning |
+| --- | --- |
+| `-w, --watch [seconds]` | Poll for changes (default 10s). Ideal during development. |
+| `--prune` | Delete local files no longer in the manifest. |
+| `--dry-run` | Print plan, write nothing. |
+| `--full` | Ignore `lastSync`; re-fetch the full manifest. |
+| `-c, --concurrency <n>` | Parallel downloads (1–16, default 6). |
+| `-q, --quiet` | Minimal output (for CI). |
+
+Sync is built to be cheap: a no-op run is one small manifest request, zero PNG bytes.
+
+- sha256 diff against disk — matching files are never re-downloaded.
+- `If-None-Match` ETag on per-asset GETs — server returns 304 if your local copy matches.
+- `lastSync` in `.magicpixel/state.json` → incremental manifest fetch (`?since=…`).
+- Atomic writes (`*.tmp` → `rename`) survive crashes mid-write.
+- Retry with backoff on 429/5xx; `lastSync` only advances on a clean run.
+
+## Config (`magicpixel.json`)
+
+| Field      | Type       | Default                 | Meaning                                          |
+| ---------- | ---------- | ----------------------- | ------------------------------------------------ |
+| `outDir`   | `string`   | framework-dependent     | Where PNGs (and `index.ts`) are written.         |
+| `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).            |
+
+State (`.magicpixel/state.json`) tracks `lastSync`. Add `.magicpixel/` to `.gitignore` (init offers to do this).
+
+## CI usage
+
+```yaml
+name: Sync MagicPixel
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '0 * * * *'
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20 }
+      - run: npx -y @magicpixel/cli sync --prune --quiet
+        env:
+          MAGICPIXEL_API_KEY: ${{ secrets.MAGICPIXEL_API_KEY }}
+      - uses: peter-evans/create-pull-request@v6
+        with:
+          commit-message: 'chore: sync MagicPixel assets'
+          branch: chore/magicpixel-sync
+          title: 'Sync MagicPixel assets'
+```
+
+## `.gitattributes` (optional)
+
+Keep PR diffs clean by marking generated PNGs:
+
+```
+src/assets/magicpixel/** binary linguist-generated=true
+```
+
+## Troubleshooting
+
+Every error message includes a `Fix:` block. Common ones:
+
+| Symptom | Fix |
+| --- | --- |
+| `MAGICPIXEL_API_KEY is not set` | Export it from your shell. |
+| `401` / `403` | Regenerate the key at magicpixel.art/settings. |
+| `whoami` shows 0 assets | The key is bound to an empty project. Mint a key for the project that has art. |
+| `index.ts` doesn't update | Run `sync --full` once; renames may take a full pass to propagate. |
+| Files keep re-downloading | Your build system is rewriting PNGs. Sync into a dir your bundler reads but doesn't mutate. |
+
+## What v1 does NOT do
+
+- Layer JSON sync (PNG only)
+- A runtime JS SDK (your bundler already handles PNG imports)
+- Cross-user asset sharing
+
+## License
+
+MIT

package/dist/api.js

@@ -0,0 +1,103 @@
+import { resolveEndpoint, getApiKey, CLI_USER_AGENT } from './config.js';
+export class ApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+function friendly(status, body, context) {
+    if (status === 401 || status === 403) {
+        return (`${context}: ${status} — API key rejected.\n` +
+            `  Fix: regenerate at https://magicpixel.art/settings and re-export MAGICPIXEL_API_KEY.`);
+    }
+    if (status === 404) {
+        return (`${context}: 404 — endpoint or asset not found.\n` +
+            `  Fix: check the "endpoint" field in magicpixel.json, or remove it to use the default.`);
+    }
+    if (status === 429) {
+        return `${context}: 429 — rate limited. Retry shortly.`;
+    }
+    if (status >= 500) {
+        return `${context}: ${status} — MagicPixel server error. Retry shortly; status at https://magicpixel.art.`;
+    }
+    return `${context}: ${status} — ${body.slice(0, 200)}`;
+}
+function authHeaders() {
+    return {
+        Authorization: `Bearer ${getApiKey()}`,
+        'User-Agent': CLI_USER_AGENT,
+    };
+}
+export async function fetchManifestPage(opts) {
+    const url = new URL(`${resolveEndpoint(opts.config)}/manifest`);
+    for (const inc of opts.config.include)
+        url.searchParams.append('include', inc);
+    for (const exc of opts.config.exclude)
+        url.searchParams.append('exclude', exc);
+    if (opts.since)
+        url.searchParams.set('since', opts.since);
+    if (opts.cursor)
+        url.searchParams.set('cursor', opts.cursor);
+    if (opts.limit)
+        url.searchParams.set('limit', String(opts.limit));
+    let res;
+    try {
+        res = await fetch(url, { headers: authHeaders() });
+    }
+    catch (e) {
+        throw new Error(`manifest: network error (${e.message}).\n` +
+            `  Fix: check your internet connection and that ${url.host} is reachable.`);
+    }
+    if (!res.ok) {
+        throw new ApiError(res.status, friendly(res.status, await res.text(), 'manifest'));
+    }
+    return (await res.json());
+}
+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;
+}
+/**
+ * Download a single asset by key. Returns null on 304 (not modified).
+ * Retries transient failures (network errors, 429, 5xx) with backoff.
+ */
+export async function fetchAssetBytes(config, key, knownSha) {
+    const url = new URL(resolveEndpoint(config));
+    url.searchParams.set('key', key);
+    const headers = authHeaders();
+    if (knownSha)
+        headers['If-None-Match'] = `"${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)
+                return null;
+            if (res.ok)
+                return new Uint8Array(await res.arrayBuffer());
+            if (res.status === 429 || res.status >= 500) {
+                lastErr = new ApiError(res.status, friendly(res.status, await res.text(), `download ${key}`));
+            }
+            else {
+                throw new ApiError(res.status, friendly(res.status, await res.text(), `download ${key}`));
+            }
+        }
+        catch (e) {
+            lastErr = e;
+            if (e instanceof ApiError && e.status < 500 && e.status !== 429)
+                throw e;
+        }
+        if (attempt < maxAttempts) {
+            await new Promise((r) => setTimeout(r, 250 * 2 ** (attempt - 1)));
+        }
+    }
+    throw lastErr ?? new Error(`download ${key}: unknown error`);
+}

package/dist/commands/add.js

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

package/dist/commands/init.js

@@ -0,0 +1,127 @@
+import kleur from 'kleur';
+import { existsSync } from 'node:fs';
+import { readFile, writeFile, appendFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import { configPath, defaultConfig, saveConfig } from '../config.js';
+export async function initCommand(opts) {
+    const path = configPath();
+    if (existsSync(path) && !opts.force) {
+        console.log(kleur.yellow(`magicpixel.json already exists. Use --force to overwrite.`));
+        return;
+    }
+    const interactive = !opts.yes && stdin.isTTY;
+    const config = { ...defaultConfig };
+    let addGitignore = true;
+    const framework = await detectFramework();
+    const suggestedOutDir = suggestOutDir(framework);
+    config.outDir = suggestedOutDir;
+    if (interactive) {
+        const rl = createInterface({ input: stdin, output: stdout });
+        try {
+            console.log(kleur.bold('Set up @magicpixel/cli'));
+            if (framework)
+                console.log(kleur.dim(`  Detected: ${framework}`));
+            console.log();
+            config.outDir = (await rl.question(`${kleur.cyan('?')} Where should assets be written? ${kleur.dim(`(${suggestedOutDir})`)} `)).trim() || suggestedOutDir;
+            // Typed index only makes sense when the outDir is importable by a bundler.
+            // public/ and static/ are served as-is and cannot be imported.
+            if (isImportableOutDir(config.outDir)) {
+                const emitAns = (await rl.question(`${kleur.cyan('?')} Emit a typed index.ts for autocomplete? ${kleur.dim('(Y/n)')} `)).trim().toLowerCase();
+                config.emitIndex = emitAns !== 'n' && emitAns !== 'no';
+            }
+            else {
+                config.emitIndex = false;
+                console.log(kleur.dim(`  Skipping typed index (outDir "${config.outDir}" is served statically, not importable).`));
+            }
+            const giAns = (await rl.question(`${kleur.cyan('?')} Add .magicpixel/ to .gitignore? ${kleur.dim('(Y/n)')} `)).trim().toLowerCase();
+            addGitignore = giAns !== 'n' && giAns !== 'no';
+        }
+        finally {
+            rl.close();
+        }
+    }
+    else {
+        config.emitIndex = isImportableOutDir(config.outDir);
+    }
+    await saveConfig(config);
+    console.log();
+    console.log(kleur.green('✓ wrote magicpixel.json'));
+    if (addGitignore) {
+        const added = await ensureGitignore();
+        if (added)
+            console.log(kleur.green('✓ added .magicpixel/ to .gitignore'));
+    }
+    console.log();
+    console.log(kleur.bold('Next:'));
+    console.log(`  1. Get an API key → ${kleur.cyan('https://magicpixel.art/settings')}`);
+    console.log(`  2. ${kleur.dim('export')} MAGICPIXEL_API_KEY=mp_live_...`);
+    console.log(`  3. ${kleur.dim('npx')} magicpixel sync`);
+    console.log();
+    console.log(kleur.dim('Tip: use `magicpixel sync --watch` while editing.'));
+}
+async function detectFramework() {
+    try {
+        const pkgPath = resolve(process.cwd(), 'package.json');
+        if (!existsSync(pkgPath))
+            return null;
+        const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        if (deps['next'])
+            return 'Next.js';
+        if (deps['vite'])
+            return 'Vite';
+        if (deps['@remix-run/react'])
+            return 'Remix';
+        if (deps['react-scripts'])
+            return 'Create React App';
+        if (deps['astro'])
+            return 'Astro';
+        if (deps['nuxt'])
+            return 'Nuxt';
+        if (deps['@sveltejs/kit'])
+            return 'SvelteKit';
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function suggestOutDir(framework) {
+    switch (framework) {
+        case 'Next.js':
+        case 'Astro':
+        case 'Nuxt':
+        case 'Create React App':
+            return 'public/magicpixel';
+        case 'SvelteKit':
+            return 'static/magicpixel';
+        case 'Vite':
+        case 'Remix':
+        default:
+            return 'src/assets/magicpixel';
+    }
+}
+/**
+ * `public/` and `static/` are served as-is by frameworks and can't be
+ * `import`ed by a bundler — emitting a typed index there is dead code that
+ * also gets shipped as a static asset.
+ */
+function isImportableOutDir(outDir) {
+    const norm = outDir.replace(/\\/g, '/').replace(/^\.\//, '');
+    return !/^(public|static)(\/|$)/.test(norm);
+}
+async function ensureGitignore() {
+    const path = resolve(process.cwd(), '.gitignore');
+    const marker = '.magicpixel/';
+    if (existsSync(path)) {
+        const current = await readFile(path, 'utf8');
+        if (current.split('\n').some((l) => l.trim() === marker))
+            return false;
+        await appendFile(path, (current.endsWith('\n') ? '' : '\n') + `\n# MagicPixel CLI state\n${marker}\n`);
+        return true;
+    }
+    await writeFile(path, `# MagicPixel CLI state\n${marker}\n`, 'utf8');
+    return true;
+}

package/dist/commands/list.js

@@ -0,0 +1,23 @@
+import kleur from 'kleur';
+import { loadConfig } from '../config.js';
+import { fetchAllManifest } from '../api.js';
+export async function listCommand() {
+    const config = await loadConfig();
+    const entries = await fetchAllManifest(config);
+    if (entries.length === 0) {
+        console.log(kleur.yellow('No matching assets.'));
+        return;
+    }
+    const widthKey = Math.max(3, ...entries.map((e) => e.key.length));
+    const widthSize = 8;
+    console.log(kleur.bold('KEY'.padEnd(widthKey)) + '  ' +
+        kleur.bold('SIZE'.padEnd(widthSize)) + '  ' +
+        kleur.bold('SHA256'));
+    for (const e of entries) {
+        const size = e.size_bytes != null ? `${e.size_bytes}B` : '-';
+        const sha = e.sha256 ? e.sha256.slice(0, 12) : '-';
+        console.log(`${e.key.padEnd(widthKey)}  ${size.padEnd(widthSize)}  ${sha}`);
+    }
+    console.log();
+    console.log(kleur.dim(`${entries.length} asset${entries.length === 1 ? '' : 's'}`));
+}

package/dist/commands/remove.js

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

package/dist/commands/status.js

@@ -0,0 +1,54 @@
+import kleur from 'kleur';
+import { loadConfig, loadState, resolveEndpoint } from '../config.js';
+import { fetchAllManifest } from '../api.js';
+import { fileSha256 } from '../util/hash.js';
+import { assetDiskPath } from '../util/paths.js';
+export async function statusCommand() {
+    const config = await loadConfig();
+    const state = await loadState();
+    console.log(kleur.bold('Config'));
+    console.log(`  outDir:   ${config.outDir}`);
+    console.log(`  include:  ${config.include.join(', ') || '(none)'}`);
+    console.log(`  exclude:  ${config.exclude.join(', ') || '(none)'}`);
+    console.log(`  endpoint: ${resolveEndpoint(config)}`);
+    console.log();
+    console.log(kleur.bold('State'));
+    console.log(`  lastSync: ${state.lastSync ?? kleur.dim('never')}`);
+    console.log();
+    console.log(kleur.bold('Auth'));
+    const key = process.env.MAGICPIXEL_API_KEY;
+    if (!key) {
+        console.log(kleur.red('  MAGICPIXEL_API_KEY not set'));
+        return;
+    }
+    console.log(`  key:      ${kleur.green('set')} (${maskKey(key)})`);
+    console.log();
+    console.log(kleur.bold('Diff vs remote'));
+    try {
+        const manifest = await fetchAllManifest(config);
+        let changed = 0;
+        let unchanged = 0;
+        let missing = 0;
+        for (const entry of manifest) {
+            const local = await fileSha256(assetDiskPath(config.outDir, entry));
+            if (!local)
+                missing++;
+            else if (entry.sha256 && entry.sha256 === local)
+                unchanged++;
+            else
+                changed++;
+        }
+        console.log(`  remote assets: ${manifest.length}`);
+        console.log(`  ${kleur.dim('=')} unchanged: ${unchanged}`);
+        console.log(`  ${kleur.yellow('~')} changed:   ${changed}`);
+        console.log(`  ${kleur.green('+')} missing:   ${missing}`);
+    }
+    catch (e) {
+        console.log(kleur.red(`  manifest fetch failed: ${e.message}`));
+    }
+}
+function maskKey(k) {
+    if (k.length <= 12)
+        return '***';
+    return `${k.slice(0, 8)}…${k.slice(-4)}`;
+}

package/dist/commands/sync.js

@@ -0,0 +1,302 @@
+import kleur from 'kleur';
+import ora from 'ora';
+import { mkdir, writeFile, unlink, readdir, rm, rename } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { loadConfig, loadState, saveState } from '../config.js';
+import { fetchAllManifest, fetchAssetBytes } from '../api.js';
+import { fileSha256 } from '../util/hash.js';
+import { assetDiskPath } from '../util/paths.js';
+import { createLimit } from '../util/limit.js';
+import { emitTypedIndex } from '../util/emitIndex.js';
+export async function syncCommand(opts) {
+    if (opts.watch) {
+        await watchLoop(opts);
+        return;
+    }
+    await runOnce(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 inFlight = false;
+    const tick = async () => {
+        if (inFlight)
+            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` : '') +
+                    (r.failed ? kleur.yellow(`, ${r.failed} failed`) : ''));
+            }
+            else {
+                process.stdout.write(`\r\x1b[2K${kleur.dim(`${timestamp()} no changes (${r.unchanged} unchanged)`)}`);
+            }
+        }
+        catch (e) {
+            console.log(`\n${kleur.dim(timestamp())} ${kleur.red('!')} ${e.message.split('\n')[0]}`);
+        }
+        finally {
+            inFlight = false;
+        }
+    };
+    await tick();
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        await new Promise((r) => setTimeout(r, intervalSec * 1000));
+        await tick();
+    }
+}
+async function runOnce(opts) {
+    const config = await loadConfig();
+    const state = await loadState();
+    const startedAt = new Date().toISOString();
+    const concurrency = Math.max(1, Math.min(opts.concurrency ?? 6, 16));
+    const quiet = !!opts.quiet;
+    // Incremental: only fetch what changed since last successful sync.
+    // --full forces a from-scratch fetch.
+    const since = opts.full ? undefined : state.lastSync;
+    const spinner = quiet
+        ? null
+        : ora(since ? `Fetching manifest since ${humanTime(since)}…` : 'Fetching manifest…').start();
+    let manifest;
+    try {
+        manifest = await fetchAllManifest(config, since);
+        spinner?.succeed(`Manifest: ${manifest.length} asset${manifest.length === 1 ? '' : 's'}${since ? kleur.dim(' (incremental)') : ''}`);
+    }
+    catch (e) {
+        spinner?.fail('Manifest fetch failed');
+        throw e;
+    }
+    // Diff
+    const toDownload = [];
+    const skipped = [];
+    let bytesSaved = 0;
+    for (const entry of manifest) {
+        const diskPath = assetDiskPath(config.outDir, entry);
+        const localSha = await fileSha256(diskPath);
+        if (entry.sha256 && localSha && entry.sha256 === localSha) {
+            skipped.push(entry);
+            if (entry.size_bytes)
+                bytesSaved += entry.size_bytes;
+        }
+        else {
+            toDownload.push(entry);
+        }
+    }
+    // Orphan detection only when we have the full picture.
+    let orphans = [];
+    if (!since) {
+        const remoteDiskPaths = new Set(manifest.map((e) => assetDiskPath(config.outDir, e)));
+        orphans = (await findLocalPngs(resolve(process.cwd(), config.outDir)))
+            .filter((p) => !remoteDiskPaths.has(p));
+    }
+    if (!quiet) {
+        console.log();
+        console.log(kleur.bold('Plan:'));
+        console.log(`  ${kleur.green('+')} download ${toDownload.length}`);
+        console.log(`  ${kleur.dim('=')} unchanged ${skipped.length}${bytesSaved ? kleur.dim(` (~${formatBytes(bytesSaved)} saved)`) : ''}`);
+        if (since) {
+            console.log(`  ${kleur.dim('orphan check skipped (incremental — use --full)')}`);
+        }
+        else if (orphans.length > 0) {
+            const verb = opts.prune ? kleur.red('delete') : kleur.yellow('keep (orphan)');
+            console.log(`  ${verb} ${orphans.length}`);
+        }
+        console.log();
+    }
+    if (opts.dryRun) {
+        if (!quiet) {
+            console.log(kleur.dim('--dry-run: no files written.'));
+            if (orphans.length > 0)
+                printOrphans(orphans);
+        }
+        return { downloaded: 0, unchanged: skipped.length, pruned: 0, failed: 0, bytesIn: 0, bytesSaved };
+    }
+    // Download with progress bar
+    const result = {
+        downloaded: 0,
+        unchanged: skipped.length,
+        pruned: 0,
+        failed: 0,
+        bytesIn: 0,
+        bytesSaved,
+    };
+    let progress = null;
+    if (!quiet && toDownload.length > 0) {
+        progress = ora({ text: progressText(0, toDownload.length, 0), spinner: 'dots' }).start();
+    }
+    const run = createLimit(concurrency);
+    let done = 0;
+    await Promise.all(toDownload.map((entry) => run(async () => {
+        const diskPath = assetDiskPath(config.outDir, entry);
+        try {
+            const localSha = await fileSha256(diskPath);
+            const bytes = await fetchAssetBytes(config, entry.key, localSha);
+            if (bytes === null) {
+                result.unchanged++;
+            }
+            else {
+                await mkdir(dirname(diskPath), { recursive: true });
+                const tmp = `${diskPath}.${process.pid}.tmp`;
+                await writeFile(tmp, bytes);
+                await rename(tmp, diskPath);
+                result.downloaded++;
+                result.bytesIn += bytes.byteLength;
+            }
+        }
+        catch (e) {
+            result.failed++;
+            progress?.stop();
+            console.log(`  ${kleur.red('!')} ${entry.key}: ${e.message.split('\n')[0]}`);
+            progress?.start();
+        }
+        finally {
+            done++;
+            if (progress)
+                progress.text = progressText(done, toDownload.length, result.bytesIn);
+        }
+    })));
+    if (progress) {
+        if (result.failed === 0)
+            progress.succeed(`Downloaded ${result.downloaded} (${formatBytes(result.bytesIn)})`);
+        else
+            progress.warn(`Downloaded ${result.downloaded}, failed ${result.failed} (${formatBytes(result.bytesIn)})`);
+    }
+    // Prune
+    if (opts.prune && orphans.length > 0) {
+        for (const p of orphans) {
+            await unlink(p);
+            if (!quiet)
+                console.log(`  ${kleur.red('-')} ${relative(process.cwd(), p)}`);
+        }
+        await pruneEmptyDirs(resolve(process.cwd(), config.outDir));
+        result.pruned = orphans.length;
+    }
+    else if (!quiet && orphans.length > 0) {
+        printOrphans(orphans);
+    }
+    // Emit typed index if enabled AND any file change happened (or first sync).
+    // In incremental mode `manifest` only contains changed entries, so we must
+    // re-fetch the full manifest (cheap — JSON only) to write a complete index.
+    if (config.emitIndex && (result.downloaded > 0 || result.pruned > 0 || !since)) {
+        try {
+            const fullManifest = since ? await fetchAllManifest(config) : manifest;
+            const indexPath = await emitTypedIndex(config.outDir, fullManifest);
+            if (!quiet)
+                console.log(kleur.dim(`  index → ${relative(process.cwd(), indexPath)}`));
+        }
+        catch (e) {
+            if (!quiet)
+                console.log(kleur.yellow(`  index emit failed: ${e.message}`));
+        }
+    }
+    if (result.failed === 0) {
+        await saveState({ lastSync: startedAt });
+    }
+    else if (!quiet) {
+        console.log(kleur.yellow(`\n${result.failed} download${result.failed === 1 ? '' : 's'} failed — lastSync not advanced. Re-run to retry.`));
+    }
+    if (!quiet) {
+        console.log();
+        const summary = `downloaded ${result.downloaded}, unchanged ${result.unchanged}` +
+            (opts.prune ? `, pruned ${result.pruned}` : '') +
+            (result.failed ? `, failed ${result.failed}` : '');
+        console.log(result.failed ? kleur.yellow(`done with errors. ${summary}`) : kleur.green(`✓ done. ${summary}`));
+    }
+    if (result.failed)
+        process.exitCode = 1;
+    return result;
+}
+function progressText(done, total, bytes) {
+    const pct = total === 0 ? 100 : Math.round((done / total) * 100);
+    const barWidth = 24;
+    const filled = Math.round((pct / 100) * barWidth);
+    const bar = '█'.repeat(filled) + '░'.repeat(barWidth - filled);
+    return `${bar}  ${done}/${total}  ${kleur.dim(formatBytes(bytes))}`;
+}
+function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
+function timestamp() {
+    const d = new Date();
+    return `[${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}:${String(d.getSeconds()).padStart(2, '0')}]`;
+}
+function humanTime(iso) {
+    try {
+        const d = new Date(iso);
+        return d.toLocaleString();
+    }
+    catch {
+        return iso;
+    }
+}
+function printOrphans(orphans) {
+    console.log();
+    console.log(kleur.yellow(`Orphaned local files (not in manifest):`));
+    for (const p of orphans) {
+        console.log(`  ${kleur.dim('?')} ${relative(process.cwd(), p)}`);
+    }
+    console.log(kleur.dim('  Run with --prune to delete them.'));
+}
+async function findLocalPngs(dir) {
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    async function walk(d) {
+        const entries = await readdir(d, { withFileTypes: true });
+        for (const ent of entries) {
+            const full = resolve(d, ent.name);
+            if (ent.isDirectory()) {
+                await walk(full);
+            }
+            else if (ent.isFile() && ent.name.toLowerCase().endsWith('.png')) {
+                out.push(full);
+            }
+        }
+    }
+    await walk(dir);
+    return out;
+}
+async function pruneEmptyDirs(root) {
+    if (!existsSync(root))
+        return;
+    async function walk(d) {
+        const entries = await readdir(d, { withFileTypes: true });
+        let isEmpty = true;
+        for (const ent of entries) {
+            const full = resolve(d, ent.name);
+            if (ent.isDirectory()) {
+                const childEmpty = await walk(full);
+                if (childEmpty) {
+                    await rm(full, { recursive: true, force: true });
+                }
+                else {
+                    isEmpty = false;
+                }
+            }
+            else {
+                isEmpty = false;
+            }
+        }
+        return isEmpty;
+    }
+    const entries = await readdir(root, { withFileTypes: true });
+    for (const ent of entries) {
+        if (ent.isDirectory()) {
+            const full = resolve(root, ent.name);
+            const empty = await walk(full);
+            if (empty)
+                await rm(full, { recursive: true, force: true });
+        }
+    }
+}

package/dist/commands/whoami.js

@@ -0,0 +1,25 @@
+import kleur from 'kleur';
+import { loadConfig, resolveEndpoint, getApiKey } from '../config.js';
+export async function whoamiCommand() {
+    const config = await loadConfig();
+    const url = new URL(`${resolveEndpoint(config)}/manifest`);
+    url.searchParams.set('limit', '1');
+    const res = await fetch(url, {
+        headers: { Authorization: `Bearer ${getApiKey()}` },
+    });
+    if (res.status === 401 || res.status === 403) {
+        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()}`));
+        process.exitCode = 1;
+        return;
+    }
+    const body = (await res.json());
+    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?')}`);
+}

package/dist/config.js

@@ -0,0 +1,80 @@
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+const CONFIG_FILENAME = 'magicpixel.json';
+const STATE_DIR = '.magicpixel';
+const STATE_FILENAME = 'state.json';
+const DEFAULT_ENDPOINT = 'https://sddsilidjhvtvejzvolx.supabase.co/functions/v1/integration-assets';
+export const defaultConfig = {
+    outDir: 'src/assets/magicpixel',
+    include: ['**/*'],
+    exclude: [],
+    emitIndex: true,
+};
+export function configPath(cwd = process.cwd()) {
+    return resolve(cwd, CONFIG_FILENAME);
+}
+export function statePath(cwd = process.cwd()) {
+    return resolve(cwd, STATE_DIR, STATE_FILENAME);
+}
+export async function loadConfig(cwd = process.cwd()) {
+    const path = configPath(cwd);
+    if (!existsSync(path)) {
+        throw new Error(`No ${CONFIG_FILENAME} found in ${cwd}.\n` +
+            `  Fix: run \`npx magicpixel init\` to create one.`);
+    }
+    const raw = await readFile(path, 'utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`${CONFIG_FILENAME} is not valid JSON: ${e.message}\n` +
+            `  Fix: open the file and check for trailing commas or quotes.`);
+    }
+    return {
+        outDir: parsed.outDir ?? defaultConfig.outDir,
+        include: parsed.include ?? defaultConfig.include,
+        exclude: parsed.exclude ?? defaultConfig.exclude,
+        endpoint: parsed.endpoint,
+        emitIndex: parsed.emitIndex ?? defaultConfig.emitIndex,
+    };
+}
+export async function saveConfig(config, cwd = process.cwd()) {
+    await writeFile(configPath(cwd), JSON.stringify(config, null, 2) + '\n', 'utf8');
+}
+export async function loadState(cwd = process.cwd()) {
+    const path = statePath(cwd);
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+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');
+}
+export function resolveEndpoint(config) {
+    return config.endpoint ?? DEFAULT_ENDPOINT;
+}
+export function getApiKey() {
+    const key = process.env.MAGICPIXEL_API_KEY;
+    if (!key) {
+        throw new Error('MAGICPIXEL_API_KEY is not set.\n' +
+            '  Fix:\n' +
+            '    1. Get a key at https://magicpixel.art/settings (API Keys).\n' +
+            '    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` +
+            `  Fix: re-copy the key from https://magicpixel.art/settings.`);
+    }
+    return key;
+}
+export const CLI_USER_AGENT = `@magicpixel/cli/0.1.0 (node ${process.versions.node})`;

package/dist/index.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import kleur from 'kleur';
+import { initCommand } from './commands/init.js';
+import { syncCommand } from './commands/sync.js';
+import { addCommand } from './commands/add.js';
+import { removeCommand } from './commands/remove.js';
+import { listCommand } from './commands/list.js';
+import { statusCommand } from './commands/status.js';
+import { whoamiCommand } from './commands/whoami.js';
+// Node version guard
+const major = Number(process.versions.node.split('.')[0]);
+if (major < 18) {
+    console.error(kleur.red(`magicpixel requires Node.js >= 18 (you have ${process.versions.node}).`));
+    process.exit(1);
+}
+const program = new Command();
+program
+    .name('magicpixel')
+    .description('Sync MagicPixel pixel-art assets to your local project')
+    .version('0.1.0');
+const wrap = (fn) => async (...args) => {
+    try {
+        await fn(...args);
+    }
+    catch (e) {
+        const msg = e.message ?? String(e);
+        // Multi-line messages are already formatted with "Fix:" hints — print as-is.
+        console.error(kleur.red(msg));
+        process.exit(1);
+    }
+};
+program
+    .command('init')
+    .description('Create magicpixel.json (interactive)')
+    .option('--force', 'Overwrite existing config')
+    .option('-y, --yes', 'Skip prompts, use defaults (CI-friendly)')
+    .action(wrap(async (opts) => initCommand(opts)));
+program
+    .command('sync')
+    .description('Download changed assets from MagicPixel')
+    .option('--prune', 'Delete local files no longer in the manifest')
+    .option('--dry-run', 'Print the plan without writing files')
+    .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))
+    .action(wrap(async (opts) => syncCommand(opts)));
+program
+    .command('add <glob>')
+    .description('Append a glob pattern to include')
+    .action(wrap(async (glob) => addCommand(glob)));
+program
+    .command('remove <glob>')
+    .description('Remove a glob pattern from include')
+    .action(wrap(async (glob) => removeCommand(glob)));
+program
+    .command('list')
+    .description('List the matching assets in the manifest')
+    .action(wrap(async () => listCommand()));
+program
+    .command('status')
+    .description('Show config, last sync, and diff vs remote')
+    .action(wrap(async () => statusCommand()));
+program
+    .command('whoami')
+    .description('Verify the API key and show what it can see')
+    .action(wrap(async () => whoamiCommand()));
+program.parseAsync(process.argv);

package/dist/util/emitIndex.js

@@ -0,0 +1,39 @@
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+/**
+ * Emit `<outDir>/index.ts` with a typed map of every asset key → URL.
+ *
+ *   import { MagicPixelAssets } from '@/assets/magicpixel';
+ *   const url = MagicPixelAssets['player/walk'];
+ *
+ * Vite, webpack, esbuild, Parcel, Rollup, etc. all hash these URLs at build
+ * 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));
+    const lines = [
+        '// AUTOGENERATED by @magicpixel/cli. Do not edit.',
+        '// Re-runs of `magicpixel sync` overwrite this file.',
+        '',
+    ];
+    for (const e of sorted) {
+        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('');
+    lines.push('export const MagicPixelAssets = {');
+    for (const e of sorted) {
+        lines.push(`  ${JSON.stringify(e.key)}: asset_${slugToIdent(e.key)},`);
+    }
+    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');
+    return path;
+}
+function slugToIdent(key) {
+    return key.replace(/[^a-zA-Z0-9]/g, '_');
+}

package/dist/util/hash.js

@@ -0,0 +1,9 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+export async function fileSha256(path) {
+    if (!existsSync(path))
+        return null;
+    const buf = await readFile(path);
+    return createHash('sha256').update(buf).digest('hex');
+}

package/dist/util/limit.js

@@ -0,0 +1,36 @@
+/**
+ * Tiny concurrency limiter. No deps.
+ *   const run = createLimit(6);
+ *   await Promise.all(items.map(item => run(() => doWork(item))));
+ */
+export function createLimit(concurrency) {
+    let active = 0;
+    const queue = [];
+    const next = () => {
+        if (active >= concurrency)
+            return;
+        const job = queue.shift();
+        if (job)
+            job();
+    };
+    return function run(fn) {
+        return new Promise((resolve, reject) => {
+            const start = () => {
+                active++;
+                fn().then((v) => {
+                    active--;
+                    resolve(v);
+                    next();
+                }, (e) => {
+                    active--;
+                    reject(e);
+                    next();
+                });
+            };
+            if (active < concurrency)
+                start();
+            else
+                queue.push(start);
+        });
+    };
+}

package/dist/util/paths.js

@@ -0,0 +1,11 @@
+import { resolve } from 'node:path';
+/**
+ * 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()) {
+    const base = resolve(cwd, outDir);
+    const file = `${entry.slug}.png`;
+    return entry.folder ? resolve(base, entry.folder, file) : resolve(base, file);
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@magicpixelart/cli",
+  "version": "0.1.0",
+  "description": "Sync MagicPixel pixel-art assets to your local project.",
+  "type": "module",
+  "bin": {
+    "magicpixel": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').chmodSync('dist/index.js', 0o755)\"",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "magicpixel",
+    "pixel-art",
+    "cli",
+    "asset-sync",
+    "gamedev",
+    "sprites"
+  ],
+  "homepage": "https://magicpixel.art",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/handpoke/magicpixel-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/magicpixel/cli/issues"
+  },
+  "license": "MIT",
+  "author": "MagicPixel",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "kleur": "^4.1.5",
+    "ora": "^8.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0"
+  }
+}