@magicpixelart/cli 0.1.2 → 0.3.3

package/dist/commands/sync.js

@@ -5,11 +5,11 @@ 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 { fetchAllManifest, fetchAssetBytes, ApiError } from '../api.js';
 import { fileSha256 } from '../util/hash.js';
-import { assetDiskPath } from '../util/paths.js';
+import { assetDiskPath, assetDiskPathFromKey } from '../util/paths.js';
 import { createLimit } from '../util/limit.js';
-import { emitTypedIndex } from '../util/emitIndex.js';
+import { emitTypedIndex, ensureAgentsDoc, scanDiskAssets } from '../util/emitIndex.js';
 import { assertPathInsideRoot, tmpPathFor } from '../util/security.js';
 export async function syncCommand(opts) {
     if (opts.watch) {
@@ -19,19 +19,46 @@ export async function syncCommand(opts) {
     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.`));
+    // Default 2s — matches the perceived-instant UX users expect when editing
+    // sprites in MagicPixel and watching them refresh in their game's dev
+    // server. Incremental polls send `?since=<lastSync>` so an empty manifest
+    // round-trip is cheap (a single HTTP HEAD-sized response with `count: 0`).
+    // Floor stays at 2s to keep accidental thrashing in check; users who need
+    // less can pass `--watch 5`.
+    const intervalSec = typeof opts.watch === 'string' ? Math.max(2, parseInt(opts.watch, 10) || 2) : 2;
+    // Header — print once on start. Project/asset count is best-effort; if the
+    // first manifest fetch fails we still want the loop to come up and retry.
+    let headerCount = null;
+    try {
+        const state = await loadState();
+        headerCount = state.assets ? Object.keys(state.assets).length : null;
+    }
+    catch {
+        // ignore — header is cosmetic
+    }
+    console.log(kleur.bold('👀 MagicPixel watching for changes…'));
+    console.log(`   Edit at:  ${kleur.cyan('https://magicpixel.art')}`);
+    if (headerCount !== null)
+        console.log(kleur.dim(`   Sprites:  ${headerCount}`));
+    console.log(kleur.dim(`   Polling:  every ${intervalSec}s   ·   Stop: Ctrl+C`));
+    console.log();
     let stopping = false;
     let inFlight = false;
     let resolveIdle = null;
+    let backoffSec = intervalSec;
+    let pausedForAuth = false;
+    // Adaptive idle backoff: after a few minutes of nothing-to-do we slow the
+    // poll from 2s → 5s → 10s so a dev who walked away isn't hammering the
+    // manifest endpoint. ANY change OR error resets this back to intervalSec,
+    // so the "edit → see it" promise stays intact the moment the user comes
+    // back. Error backoff (2→60s) is separate and continues to win.
+    let consecutiveIdleTicks = 0;
     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));
         }
@@ -41,25 +68,68 @@ async function watchLoop(opts) {
         }
     };
     process.on('SIGINT', onSigint);
-    // Run once eagerly so first sync isn't delayed by the interval.
     const tick = async () => {
         if (inFlight || stopping)
             return;
         inFlight = true;
         try {
-            const r = await runOnce({ ...opts, quiet: true, watch: false });
-            if (r.downloaded > 0 || r.pruned > 0) {
+            const r = await runOnce({ ...opts, watch: false }, { watchMode: true });
+            // Reset backoff + auth-pause flags on any successful tick.
+            backoffSec = intervalSec;
+            pausedForAuth = false;
+            const changedCount = r.added.length + r.modified.length + r.removed.length + r.renamed.length;
+            if (changedCount > 0) {
+                // Snap back to the fast interval the moment anything changes.
+                consecutiveIdleTicks = 0;
+                backoffSec = intervalSec;
+            }
+            else {
+                consecutiveIdleTicks++;
+                // Thresholds in *ticks*; at intervalSec=2 these are ~3 min and ~15 min.
+                if (consecutiveIdleTicks >= 300)
+                    backoffSec = Math.max(intervalSec, 10);
+                else if (consecutiveIdleTicks >= 90)
+                    backoffSec = Math.max(intervalSec, 5);
+            }
+            if (opts.quiet)
+                return;
+            if (changedCount > 0) {
                 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`) : ''));
+                const verb = r.removed.length && !r.added.length && !r.modified.length ? 'Removed' : 'Pulled';
+                console.log(`${kleur.dim(timestamp())} ${kleur.green('✓')} ${verb} ${changedCount} ` +
+                    `change${changedCount === 1 ? '' : 's'} from MagicPixel:`);
+                printChanges(r, /* indent */ '  ');
             }
             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]}`);
+            const err = e;
+            const apiErr = err instanceof ApiError ? err : null;
+            const firstLine = err.message.split('\n')[0];
+            process.stdout.write('\x1b[2K\r');
+            // Any error breaks the idle streak so we come back fast once it clears.
+            consecutiveIdleTicks = 0;
+            if (apiErr && (apiErr.status === 401 || apiErr.status === 403)) {
+                if (!pausedForAuth) {
+                    console.log(`${kleur.dim(timestamp())} ${kleur.red('✗')} Your key looks invalid or rotated.`);
+                    console.log(kleur.dim('   Fix: run `magicpixel login` (this watcher will keep retrying every 30s).'));
+                }
+                pausedForAuth = true;
+                backoffSec = 30;
+            }
+            else if (isNetworkError(err)) {
+                if (backoffSec < 30) {
+                    console.log(`${kleur.dim(timestamp())} ${kleur.yellow('!')} MagicPixel is offline or your internet is. ` +
+                        `Sprites you already have still work. Retrying in ${Math.min(backoffSec * 2, 60)}s.`);
+                }
+                backoffSec = Math.min(backoffSec * 2, 60);
+            }
+            else {
+                console.log(`${kleur.dim(timestamp())} ${kleur.red('!')} ${firstLine}`);
+                backoffSec = Math.min(backoffSec * 2, 60);
+            }
         }
         finally {
             inFlight = false;
@@ -69,12 +139,11 @@ async function watchLoop(opts) {
     };
     await tick();
     while (!stopping) {
-        await new Promise((r) => setTimeout(r, intervalSec * 1000));
+        await new Promise((r) => setTimeout(r, backoffSec * 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;
@@ -83,23 +152,29 @@ async function watchLoop(opts) {
     console.log(kleur.dim('[watch] stopped.'));
     process.exit(0);
 }
-async function runOnce(opts) {
+function isNetworkError(err) {
+    // The api layer wraps fetch failures as `manifest: network error (...)`;
+    // bare ENOTFOUND/ETIMEDOUT/etc. also surface here from `fetchAssetBytes`.
+    const msg = err.message;
+    return (/network error/i.test(msg) ||
+        /ENOTFOUND|ETIMEDOUT|ECONNRESET|ECONNREFUSED|EAI_AGAIN/i.test(msg) ||
+        /fetch failed/i.test(msg));
+}
+async function runOnce(opts, runOpts = {}) {
     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;
-    // 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) {
+    const verbose = !opts.quiet && !runOpts.watchMode;
+    const shouldPrune = opts.prune !== false; // commander: --no-prune sets false
+    if (verbose && 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;
-    const spinner = quiet
-        ? null
-        : ora(since ? `Fetching manifest since ${humanTime(since)}…` : 'Fetching manifest…').start();
+    const previousAssets = state.assets ?? {}; // id → key from prior sync
+    const spinner = verbose
+        ? ora(since ? `Fetching manifest since ${humanTime(since)}…` : 'Fetching manifest…').start()
+        : null;
     let manifest;
     try {
         manifest = await fetchAllManifest(config, since);
@@ -109,15 +184,23 @@ async function runOnce(opts) {
         spinner?.fail('Manifest fetch failed');
         throw e;
     }
-    // Diff
+    // Detect renames: same id, different key vs prior snapshot.
+    const renamed = [];
+    for (const entry of manifest) {
+        const prevKey = previousAssets[entry.id];
+        if (prevKey && prevKey !== entry.key) {
+            renamed.push({ id: entry.id, oldKey: prevKey, newKey: entry.key });
+        }
+    }
+    // Diff against disk
     const toDownload = [];
-    const skipped = [];
     let bytesSaved = 0;
+    let unchanged = 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);
+            unchanged++;
             if (entry.size_bytes)
                 bytesSaved += entry.size_bytes;
         }
@@ -126,51 +209,77 @@ async function runOnce(opts) {
         }
     }
     // Orphan detection only when we have the full picture.
+    // (Renames also produce a stale path on disk — collected separately below.)
     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) {
+    // Stale paths from detected renames (always pruned, even in incremental mode —
+    // otherwise the old PNG silently lingers next to the renamed copy).
+    const renameStalePaths = renamed
+        .map((r) => assetDiskPathFromKey(config.outDir, r.oldKey))
+        .filter((p) => existsSync(p));
+    // De-duplicate vs the full-sync orphan list.
+    const orphanSet = new Set(orphans);
+    for (const p of renameStalePaths)
+        orphanSet.add(p);
+    orphans = [...orphanSet];
+    if (verbose) {
         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('=')} unchanged ${unchanged}${bytesSaved ? kleur.dim(` (~${formatBytes(bytesSaved)} saved)`) : ''}`);
+        if (renamed.length)
+            console.log(`  ${kleur.cyan('↪')} renamed ${renamed.length}`);
+        if (since && !renamed.length) {
             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)');
+            const verb = shouldPrune ? kleur.red('delete') : kleur.yellow('keep (orphan)');
             console.log(`  ${verb} ${orphans.length}`);
         }
         console.log();
     }
     if (opts.dryRun) {
-        if (!quiet) {
+        if (verbose) {
             console.log(kleur.dim('--dry-run: no files written.'));
+            if (renamed.length > 0)
+                printRenames(renamed, { withHints: false });
             if (orphans.length > 0)
                 printOrphans(orphans);
         }
-        return { downloaded: 0, unchanged: skipped.length, pruned: 0, failed: 0, bytesIn: 0, bytesSaved };
+        return {
+            added: [],
+            modified: [],
+            unchanged,
+            removed: [],
+            renamed,
+            failed: 0,
+            bytesIn: 0,
+            bytesSaved,
+        };
     }
-    // Download with progress bar
     const result = {
-        downloaded: 0,
-        unchanged: skipped.length,
-        pruned: 0,
+        added: [],
+        modified: [],
+        unchanged,
+        removed: [],
+        renamed,
         failed: 0,
         bytesIn: 0,
         bytesSaved,
     };
     let progress = null;
-    if (!quiet && toDownload.length > 0) {
+    if (verbose && 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);
+        const existedBefore = existsSync(diskPath);
         try {
             const localSha = await fileSha256(diskPath);
             const bytes = await fetchAssetBytes(config, entry.key, localSha);
@@ -178,8 +287,6 @@ 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) {
@@ -191,7 +298,10 @@ async function runOnce(opts) {
                 assertPathInsideRoot(tmp, resolve(process.cwd(), config.outDir), 'outDir');
                 await writeFile(tmp, bytes);
                 await rename(tmp, diskPath);
-                result.downloaded++;
+                if (existedBefore)
+                    result.modified.push(entry.key);
+                else
+                    result.added.push(entry.key);
                 result.bytesIn += bytes.byteLength;
             }
         }
@@ -207,59 +317,146 @@ async function runOnce(opts) {
                 progress.text = progressText(done, toDownload.length, result.bytesIn);
         }
     })));
+    const downloaded = result.added.length + result.modified.length;
     if (progress) {
         if (result.failed === 0)
-            progress.succeed(`Downloaded ${result.downloaded} (${formatBytes(result.bytesIn)})`);
+            progress.succeed(`Downloaded ${downloaded} (${formatBytes(result.bytesIn)})`);
         else
-            progress.warn(`Downloaded ${result.downloaded}, failed ${result.failed} (${formatBytes(result.bytesIn)})`);
+            progress.warn(`Downloaded ${downloaded}, failed ${result.failed} (${formatBytes(result.bytesIn)})`);
     }
-    // Prune
-    if (opts.prune && orphans.length > 0) {
+    // Prune (now default — pass --no-prune to opt out).
+    if (shouldPrune && 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)}`);
+            try {
+                await unlink(p);
+                const relPath = relative(outRoot, p).replace(/\\/g, '/');
+                const key = relPath.endsWith('.png') ? relPath.slice(0, -4) : relPath;
+                result.removed.push(key);
+                if (verbose)
+                    console.log(`  ${kleur.red('-')} ${relative(process.cwd(), p)}`);
+            }
+            catch (e) {
+                if (verbose)
+                    console.log(`  ${kleur.yellow('!')} failed to prune ${relative(process.cwd(), p)}: ${e.message}`);
+            }
         }
         await pruneEmptyDirs(resolve(process.cwd(), config.outDir));
-        result.pruned = orphans.length;
     }
-    else if (!quiet && orphans.length > 0) {
+    else if (verbose && 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}`));
+    // Always persist the id → key snapshot so rename detection survives even
+    // when `emitIndex` is toggled off-then-on. `lastSync` only advances on a
+    // clean run, so partial-failure syncs are retried from the prior cursor.
+    const nextAssets = { ...previousAssets };
+    // Drop renamed ids (they'll be re-added with the new key below).
+    for (const r of renamed)
+        delete nextAssets[r.id];
+    for (const e of manifest)
+        nextAssets[e.id] = e.key;
+    // Drop ids whose key was pruned (orphans we just removed from disk).
+    if (result.removed.length > 0) {
+        const removedKeys = new Set(result.removed);
+        for (const [id, key] of Object.entries(nextAssets)) {
+            if (removedKeys.has(key))
+                delete nextAssets[id];
         }
     }
+    const nextState = { ...state, assets: nextAssets };
     if (result.failed === 0) {
-        await saveState({ lastSync: startedAt });
+        nextState.lastSync = startedAt;
+        delete nextState.lastError;
+    }
+    else {
+        nextState.lastError = `${result.failed} download${result.failed === 1 ? '' : 's'} failed at ${startedAt}`;
+    }
+    // Emit typed index from the filesystem — never from the manifest. This
+    // guarantees the barrel can never disagree with what bundlers see on disk,
+    // and removes the silent-failure mode where a flaky manifest call left
+    // `index.ts` stale despite the PNGs being fresh.
+    if (config.emitIndex) {
+        const idByKey = {};
+        for (const [id, key] of Object.entries(nextAssets))
+            idByKey[key] = id;
+        const diskEntries = await scanDiskAssets(config.outDir);
+        for (const e of diskEntries) {
+            if (idByKey[e.key])
+                e.id = idByKey[e.key];
+        }
+        const indexPath = await emitTypedIndex(config.outDir, diskEntries);
+        if (verbose)
+            console.log(kleur.dim(`  index → ${relative(process.cwd(), indexPath)}`));
+        // Nudge AI tools toward the typed index. Idempotent — `ensureAgentsDoc`
+        // no-ops once our marker section is present.
+        try {
+            const agentsResult = await ensureAgentsDoc(config.outDir);
+            if (verbose && agentsResult !== 'unchanged') {
+                console.log(kleur.dim(`  AGENTS.md ${agentsResult}`));
+            }
+        }
+        catch {
+            // Never let an AGENTS.md write failure break sync.
+        }
     }
-    else if (!quiet) {
+    await saveState(nextState);
+    if (result.failed > 0 && verbose) {
         console.log(kleur.yellow(`\n${result.failed} download${result.failed === 1 ? '' : 's'} failed — lastSync not advanced. Re-run to retry.`));
     }
-    if (!quiet) {
+    if (verbose) {
         console.log();
-        const summary = `downloaded ${result.downloaded}, unchanged ${result.unchanged}` +
-            (opts.prune ? `, pruned ${result.pruned}` : '') +
+        const summary = `downloaded ${downloaded} (added ${result.added.length}, modified ${result.modified.length}), ` +
+            `unchanged ${result.unchanged}` +
+            (result.bytesSaved ? kleur.dim(` (~${formatBytes(result.bytesSaved)} saved)`) : '') +
+            (shouldPrune ? `, pruned ${result.removed.length}` : '') +
+            (renamed.length ? `, renamed ${renamed.length}` : '') +
             (result.failed ? `, failed ${result.failed}` : '');
         console.log(result.failed ? kleur.yellow(`done with errors. ${summary}`) : kleur.green(`✓ done. ${summary}`));
+        printChanges(result, '  ');
+        if (renamed.length > 0)
+            printRenames(renamed, { withHints: true });
     }
     if (result.failed)
         process.exitCode = 1;
     return result;
 }
+const CHANGE_PRINT_CAP = 50;
+function printChanges(r, indent) {
+    const lines = [];
+    for (const k of r.added)
+        lines.push(`${indent}${kleur.green('+')} ${k}`);
+    for (const k of r.modified)
+        lines.push(`${indent}${kleur.cyan('~')} ${k}`);
+    for (const r2 of r.renamed)
+        lines.push(`${indent}${kleur.cyan('↪')} ${r2.oldKey} → ${r2.newKey}`);
+    for (const k of r.removed)
+        lines.push(`${indent}${kleur.red('-')} ${k}`);
+    if (lines.length === 0)
+        return;
+    if (lines.length <= CHANGE_PRINT_CAP) {
+        for (const l of lines)
+            console.log(l);
+    }
+    else {
+        for (const l of lines.slice(0, CHANGE_PRINT_CAP))
+            console.log(l);
+        console.log(`${indent}${kleur.dim(`…and ${lines.length - CHANGE_PRINT_CAP} more`)}`);
+    }
+}
+function printRenames(renamed, opts) {
+    if (renamed.length === 0)
+        return;
+    console.log();
+    console.log(opts.withHints ? kleur.bold('Renamed assets — update imports:') : kleur.cyan('Renames detected:'));
+    for (const r of renamed) {
+        console.log(`  ${kleur.cyan('↪')} ${r.oldKey} → ${r.newKey}`);
+        if (opts.withHints) {
+            console.log(`    ${kleur.dim(`MagicPixelAssets['${r.oldKey}']  →  MagicPixelAssets['${r.newKey}']`)}`);
+            console.log(`    ${kleur.dim(`or pin to id:  MagicPixelAssetsById['${r.id}']  (survives future renames)`)}`);
+        }
+    }
+}
 function progressText(done, total, bytes) {
     const pct = total === 0 ? 100 : Math.round((done / total) * 100);
     const barWidth = 24;
@@ -280,8 +477,7 @@ function timestamp() {
 }
 function humanTime(iso) {
     try {
-        const d = new Date(iso);
-        return d.toLocaleString();
+        return new Date(iso).toLocaleString();
     }
     catch {
         return iso;
@@ -293,7 +489,7 @@ function printOrphans(orphans) {
     for (const p of orphans) {
         console.log(`  ${kleur.dim('?')} ${relative(process.cwd(), p)}`);
     }
-    console.log(kleur.dim('  Run with --prune to delete them.'));
+    console.log(kleur.dim('  Pruning is on by default. Re-run without --no-prune to delete them.'));
 }
 async function findLocalPngs(dir) {
     if (!existsSync(dir))
@@ -313,6 +509,8 @@ async function findLocalPngs(dir) {
                 continue;
             }
             if (ent.isDirectory()) {
+                if (ent.name.startsWith('.'))
+                    continue;
                 await walk(full);
             }
             else if (ent.isFile() && ent.name.toLowerCase().endsWith('.png')) {

package/dist/config.js

@@ -2,6 +2,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';
+import { readCredentialsSync } from './util/credentials.js';
 const CONFIG_FILENAME = 'magicpixel.json';
 const STATE_DIR = '.magicpixel';
 const STATE_FILENAME = 'state.json';
@@ -101,23 +102,38 @@ export function resolveEndpoint(config) {
         return config.endpoint;
     return DEFAULT_ENDPOINT;
 }
+/**
+ * Read the API key. Precedence: `MAGICPIXEL_API_KEY` env var (highest, so CI
+ * can always override) > `.magicpixel/credentials` (written by `magicpixel
+ * login`). Throws a friendly error pointing at `magicpixel login` when neither
+ * source is configured.
+ */
 export function getApiKey() {
-    const key = process.env.MAGICPIXEL_API_KEY;
+    const fromEnv = process.env.MAGICPIXEL_API_KEY;
+    let key = fromEnv;
+    let source = 'env';
     if (!key) {
-        throw new Error('MAGICPIXEL_API_KEY is not set.\n' +
+        const stored = readCredentialsSync();
+        if (stored) {
+            key = stored.apiKey;
+            source = 'credentials-file';
+        }
+    }
+    if (!key) {
+        throw new Error('No MagicPixel API key found.\n' +
             '  Fix:\n' +
             '    1. Get a key at https://magicpixel.art/settings (API Keys).\n' +
-            '    2. export MAGICPIXEL_API_KEY=mp_live_...\n' +
+            '    2. Run `magicpixel login` (or `export MAGICPIXEL_API_KEY=mp_live_...`).\n' +
             '    3. Re-run the command.');
     }
     const trimmed = key.trim();
-    if (trimmed !== key) {
+    if (trimmed !== key && source === 'env') {
         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.`);
+        throw new Error(`MagicPixel API key does not look right (expected mp_live_… or mp_test_…).\n` +
+            `  Fix: run \`magicpixel login\` and paste a fresh key from https://magicpixel.art/settings.`);
     }
     return trimmed;
 }

package/dist/index.js

@@ -8,6 +8,10 @@ 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 { loginCommand } from './commands/login.js';
+import { logoutCommand } from './commands/logout.js';
+import { doctorCommand } from './commands/doctor.js';
+import { startCommand } from './commands/start.js';
 import { CLI_VERSION } from './version.js';
 // Node version guard
 const major = Number(process.versions.node.split('.')[0]);
@@ -31,16 +35,34 @@ const wrap = (fn) => async (...args) => {
         process.exit(1);
     }
 };
+program
+    .command('start')
+    .description('One-command first-run setup: init + login + first sync')
+    .option('--force', 'Re-run init even if magicpixel.json exists')
+    .action(wrap(async (opts) => startCommand(opts)));
 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('login')
+    .description('Save your MagicPixel API key to .magicpixel/credentials')
+    .option('--key <key>', 'Provide the key non-interactively')
+    .action(wrap(async (opts) => loginCommand(opts)));
+program
+    .command('logout')
+    .description('Remove the stored MagicPixel API key')
+    .action(wrap(async () => logoutCommand()));
+program
+    .command('doctor')
+    .description('Print a single-page diagnostic to paste to your AI agent')
+    .action(wrap(async () => doctorCommand()));
 program
     .command('sync')
     .description('Download changed assets from MagicPixel')
-    .option('--prune', 'Delete local files no longer in the manifest')
+    .option('--no-prune', 'Keep local files not in the manifest (pruning is now on by default)')
     .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)