@magicpixelart/cli 0.5.4 → 0.5.6

package/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.5.6] — 2026-08-21
+
+### Changed
+
+- **README positioning.** Lead with generation, reskins/variants, the full
+  browser editor, and MCP/CLI instead of sprites/tilesets/direction sheets.
+
+### Fixed
+
+- **Transient Supabase 546 (edge worker recycle).** Friendly error copy for
+  status 546, five retry attempts with a longer backoff (~7.5s coverage), and
+  546s are no longer reported as telemetry noise. Persistent 5xx still reports.
+  Shape-guard tests that exhaust those retries now use a 15s budget so CI
+  matches the new backoff.
+
+## [0.5.5] — 2026-07-12
+
+### Added
+
+- **Bound project name in `whoami` / `status` / `sync`.** Manifest responses
+  now expose the API key's project via `x-magicpixel-project-*` headers and an
+  optional `project` body field. The CLI surfaces `project: <name>` so a
+  key-bound-to-the-wrong-project mistake is obvious at a glance. On empty
+  fresh syncs the server may also send `totalInProject` + a ready-to-print
+  `hint`; `whoami`, `status`, and verbose `sync` print it instead of a silent
+  zero. Old servers without the headers keep working — the project line is
+  simply omitted.
+
 ## [0.5.4] — 2026-06-22
 
 ### Added

package/README.md

@@ -1,6 +1,8 @@
 # @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.
+Sync your [MagicPixel](https://magicpixel.art) pixel-art assets to your local project as flattened PNGs. Zero runtime — just files on disk that your bundler picks up.
+
+MagicPixel is an [AI pixel art generator](https://magicpixel.art) for game developers: generate new pixel art, reskin and remix the assets you already have, and finish them in a full browser editor — then pull them straight into your repo with this CLI. It also exposes a [Model Context Protocol server](https://magicpixel.art/guides/connect) so Claude, ChatGPT, and Cursor can generate assets for you, and a [Vite plugin](https://www.npmjs.com/package/@magicpixelart/vite) that syncs on save with no second terminal.
 
 ## Install
 
@@ -205,6 +207,14 @@ at a non-canonical host.
 - A runtime JS SDK (your bundler already handles PNG imports)
 - Cross-user asset sharing
 
+## More about MagicPixel
+
+- [AI pixel art generator](https://magicpixel.art) — generate new pixel art, and reskin or remix the assets you already have.
+- [Pixel art editor](https://magicpixel.art/pixel-art-editor) — palette remapping, components, pixel-accurate cleanup, and animation frames.
+- [Generating game sprites with AI](https://magicpixel.art/guides/generating-sprites) — the workflow for game-ready assets.
+- [Editing AI pixel art](https://magicpixel.art/guides/editing-ai-art) — cleaning up and iterating on generated sprites.
+- [Connect an AI agent over MCP](https://magicpixel.art/guides/connect) — Claude, ChatGPT, and Cursor.
+
 ## License
 
 MIT

package/dist/api.js

@@ -1,6 +1,21 @@
 import { resolveEndpoint, getApiKey, CLI_VERSION } from './config.js';
 import { etagForSha256, MAX_ASSET_BYTES, readBodyWithLimit, safeFetch, } from './util/security.js';
 import { authHeaders } from './util/authHeaders.js';
+/**
+ * Last-seen project metadata from any manifest response this process made.
+ * Populated as a side-effect of `fetchManifestPage`; read by `whoami`,
+ * `status`, and `sync` to surface `project: <name>` diagnostics.
+ *
+ * Never null after the first successful manifest call. Module-level so the
+ * three commands don't have to thread it through every helper.
+ */
+let lastProjectInfo = null;
+export function getLastProjectInfo() {
+    return lastProjectInfo;
+}
+export function __resetLastProjectInfoForTesting() {
+    lastProjectInfo = null;
+}
 /**
  * Error from the MagicPixel API. `requestId` is the `X-Request-Id` the server
  * echoed (or the one we minted client-side if the server didn't respond) —
@@ -32,6 +47,11 @@ function friendly(status, body, context) {
     if (status === 429) {
         return `${context}: 429 — rate limited. Retry shortly.`;
     }
+    if (status === 546) {
+        // Supabase Edge Runtime platform code — worker boot / CPU / wall-time.
+        // Not one of ours; typically clears in seconds.
+        return `${context}: 546 — MagicPixel edge worker restarting. Retried automatically; if this persists, retry in ~30s.`;
+    }
     if (status >= 500) {
         return `${context}: ${status} — MagicPixel server error. Retry shortly; status at https://magicpixel.art.`;
     }
@@ -86,6 +106,29 @@ export async function fetchManifestPage(opts) {
             if (!isObject || !Array.isArray(data.items) || !cursorOk) {
                 throw new ApiError(502, withRequestId('manifest: unexpected server response shape (items missing or non-string cursor).', serverRequestId), serverRequestId);
             }
+            // Capture the bound project's name/id from response headers (always
+            // present on 2xx). The body may also carry a richer `project` payload
+            // (empty fresh-sync case, includes totalInProject + hint). Prefer the
+            // body when present so `whoami`/`sync` can print the "0 assets in this
+            // project" nudge without another round-trip.
+            const projectId = res.headers.get('x-magicpixel-project-id');
+            const projectName = res.headers.get('x-magicpixel-project-name');
+            const bodyProject = data.project;
+            if (bodyProject && typeof bodyProject === 'object' && typeof bodyProject.id === 'string') {
+                lastProjectInfo = {
+                    id: bodyProject.id,
+                    name: typeof bodyProject.name === 'string' ? bodyProject.name : (projectName ?? null),
+                    totalInProject: typeof bodyProject.totalInProject === 'number'
+                        ? bodyProject.totalInProject
+                        : undefined,
+                    hint: typeof bodyProject.hint === 'string'
+                        ? bodyProject.hint
+                        : undefined,
+                };
+            }
+            else if (projectId) {
+                lastProjectInfo = { id: projectId, name: projectName };
+            }
             return data;
         }
         const bodyText = await res.text();
@@ -102,7 +145,10 @@ export async function fetchManifestPage(opts) {
  *   request-id of the most recent attempt.
  */
 export async function retryTransient(context, fn) {
-    const maxAttempts = 3;
+    // 5 attempts × (500ms, 1s, 2s, 4s) = ~7.5s of coverage. Enough to ride out
+    // a Supabase edge worker recycle (546) or a brief 5xx without surfacing to
+    // the user; short enough that a real outage still fails within one sync tick.
+    const maxAttempts = 5;
     let lastErr = null;
     let nextDelayMs = 0;
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
@@ -126,7 +172,7 @@ export async function retryTransient(context, fn) {
                 nextDelayMs = 0;
             }
             if (attempt < maxAttempts) {
-                const backoffMs = 250 * 2 ** (attempt - 1);
+                const backoffMs = 500 * 2 ** (attempt - 1);
                 await new Promise((r) => setTimeout(r, Math.max(nextDelayMs, backoffMs)));
             }
         }

package/dist/commands/status.js

@@ -1,6 +1,6 @@
 import kleur from 'kleur';
 import { loadConfig, loadState, resolveEndpoint } from '../config.js';
-import { fetchAllManifest } from '../api.js';
+import { fetchAllManifest, getLastProjectInfo } from '../api.js';
 import { fileSha256 } from '../util/hash.js';
 import { assetDiskPath } from '../util/paths.js';
 import { readKeyForDisplay } from '../util/credentials.js';
@@ -66,10 +66,18 @@ export async function statusCommand() {
             else
                 changed++;
         })));
-        console.log(`  remote assets: ${manifest.length}`);
+        const project = getLastProjectInfo();
+        const projectSuffix = project ? kleur.dim(` (project: ${project.name ?? project.id.slice(0, 8)})`) : '';
+        console.log(`  remote assets: ${manifest.length}${projectSuffix}`);
         console.log(`  ${kleur.dim('=')} unchanged: ${unchanged}`);
         console.log(`  ${kleur.yellow('~')} changed:   ${changed}`);
         console.log(`  ${kleur.green('+')} missing:   ${missing}`);
+        if (manifest.length === 0 && project?.hint) {
+            // Fresh sync into an empty-project key — surface the server's hint so
+            // a project mismatch is one glance away instead of a silent zero.
+            console.log();
+            console.log(kleur.yellow(`  ${project.hint}`));
+        }
     }
     catch (e) {
         console.log(kleur.red(`  manifest fetch failed: ${e.message.split('\n')[0]}`));

package/dist/commands/sync.js

@@ -5,7 +5,7 @@ import { mkdir, unlink, readdir, rm, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { dirname, relative, resolve } from 'node:path';
 import { loadConfig, loadState, saveState } from '../config.js';
-import { fetchAllManifest, fetchAssetBytes, ApiError } from '../api.js';
+import { fetchAllManifest, fetchAssetBytes, ApiError, getLastProjectInfo } from '../api.js';
 import { fileSha256 } from '../util/hash.js';
 import { assetDiskPath, assetDiskPathFromKey, pruneEmptyDirs, walkOutDirPngs } from '../util/paths.js';
 import { createLimit } from '../util/limit.js';
@@ -319,7 +319,19 @@ async function runOnce(opts, runOpts = {}) {
     let manifest;
     try {
         manifest = await fetchAllManifest(config, since);
-        spinner?.succeed(`Manifest: ${manifest.length} asset${manifest.length === 1 ? '' : 's'}${since ? kleur.dim(' (incremental)') : ''}`);
+        const projectInfo = getLastProjectInfo();
+        const projectSuffix = projectInfo && verbose
+            ? kleur.dim(` · project: ${projectInfo.name ?? projectInfo.id.slice(0, 8)}`)
+            : '';
+        spinner?.succeed(`Manifest: ${manifest.length} asset${manifest.length === 1 ? '' : 's'}${since ? kleur.dim(' (incremental)') : ''}${projectSuffix}`);
+        // Fresh full sync + zero assets = almost always a project-scope mismatch
+        // (the exact case the "0 assets" support flow hits). Server includes a
+        // ready-to-print hint on the empty-fresh-sync response; surface it once
+        // so the user isn't left wondering why sync "did nothing".
+        if (!since && manifest.length === 0 && projectInfo?.hint && verbose) {
+            console.log();
+            console.log(kleur.yellow(`! ${projectInfo.hint}`));
+        }
     }
     catch (e) {
         spinner?.fail('Manifest fetch failed');

package/dist/commands/whoami.js

@@ -1,6 +1,6 @@
 import kleur from 'kleur';
 import { loadConfig, defaultConfig, resolveEndpoint, getApiKey } from '../config.js';
-import { ApiError, retryTransient, retryAfterMsFromResponse } from '../api.js';
+import { ApiError, retryTransient, retryAfterMsFromResponse, getLastProjectInfo } from '../api.js';
 import { safeFetch } from '../util/security.js';
 import { authHeaders } from '../util/authHeaders.js';
 export async function whoamiCommand() {
@@ -49,7 +49,25 @@ export async function whoamiCommand() {
             items: Array.isArray(raw.items) ? raw.items.filter((i) => !!i && typeof i.key === 'string') : [],
             nextCursor: typeof raw.nextCursor === 'string' && raw.nextCursor ? raw.nextCursor : null,
         };
-        return { kind: 'ok', body, serverRequestId };
+        // Prefer body.project (has totalInProject + hint on empty fresh syncs);
+        // fall back to response headers so paginated / non-empty responses still
+        // surface the bound project name. Kept in sync with fetchManifestPage.
+        const bodyProject = raw.project;
+        const projectId = res.headers.get('x-magicpixel-project-id');
+        const projectName = res.headers.get('x-magicpixel-project-name');
+        let project = null;
+        if (bodyProject && typeof bodyProject === 'object' && typeof bodyProject.id === 'string') {
+            project = {
+                id: bodyProject.id,
+                name: typeof bodyProject.name === 'string' ? bodyProject.name : (projectName ?? null),
+                totalInProject: typeof bodyProject.totalInProject === 'number' ? bodyProject.totalInProject : undefined,
+                hint: typeof bodyProject.hint === 'string' ? bodyProject.hint : undefined,
+            };
+        }
+        else if (projectId) {
+            project = { id: projectId, name: projectName };
+        }
+        return { kind: 'ok', body, project, serverRequestId };
     });
     if (result.kind === 'rejected') {
         console.log(kleur.red(`✗ API key rejected (${result.status}).`));
@@ -64,15 +82,33 @@ export async function whoamiCommand() {
         process.exitCode = 1;
         return;
     }
-    const { body } = result;
+    const { body, project } = result;
     const more = body.nextCursor ? '+' : '';
     console.log(kleur.green('✓ key valid'));
     console.log(`  endpoint: ${resolveEndpoint(config)}`);
+    if (project) {
+        const label = project.name ?? '(unnamed)';
+        console.log(`  project:  ${label} ${kleur.dim(`(${project.id.slice(0, 8)}…)`)}`);
+    }
     if (body.count === 0) {
-        console.log(`  visible:  ${kleur.yellow('0 assets — is the key bound to a project with content?')}`);
+        if (project?.hint) {
+            // Server-provided hint already names the project; use it verbatim.
+            console.log(`  visible:  ${kleur.yellow('0 assets')}`);
+            console.log(kleur.dim(`  ${project.hint}`));
+        }
+        else if (project) {
+            console.log(`  visible:  ${kleur.yellow(`0 assets in project "${project.name ?? project.id.slice(0, 8)}"`)}`);
+            console.log(kleur.dim(`  If your art lives in another project, create a key from that project's row in Settings → Projects & API Keys.`));
+        }
+        else {
+            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 ?? '-'})`);
     }
+    // Reference the module-singleton to avoid an unused-import lint on the
+    // getLastProjectInfo helper (whoami reads project data inline).
+    void getLastProjectInfo;
 }

package/dist/util/telemetry.js

@@ -41,6 +41,13 @@ export function shouldReportCliError(err) {
     if (!(err instanceof Error))
         return false;
     if (err instanceof ApiError) {
+        // 546 is a Supabase Edge Runtime platform code (worker boot / CPU /
+        // wall-time). It bypasses our function's try/catch and is almost always
+        // transient. Retries usually absorb it; a leaked-to-user 546 is still
+        // unactionable noise on /admin/errors. Persistent worker failures still
+        // surface as 500/502/503, which remain reported.
+        if (err.status === 546)
+            return false;
         // User/config issues have actionable fix hints already; don't add noise.
         return err.status >= 500;
     }

package/package.json

@@ -1,17 +1,12 @@
 {
   "name": "@magicpixelart/cli",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "Sync MagicPixel pixel-art assets to your local project.",
   "type": "module",
   "bin": {
     "magicpixel": "dist/index.js"
   },
-  "files": [
-    "dist",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
+  "files": ["dist", "README.md", "CHANGELOG.md", "LICENSE"],
   "scripts": {
     "build": "tsc && chmod +x dist/index.js",
     "dev": "tsx src/index.ts",