@magicpixelart/cli 0.5.4 → 0.5.5

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [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/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) —
@@ -86,6 +101,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();

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/package.json

@@ -1,17 +1,12 @@
 {
   "name": "@magicpixelart/cli",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "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",