@magicpixelart/cli 0.3.0 → 0.4.0

package/dist/commands/whoami.js

@@ -1,30 +1,70 @@
 import kleur from 'kleur';
-import { loadConfig, resolveEndpoint, getApiKey } from '../config.js';
-import { CLI_USER_AGENT } from '../version.js';
+import { loadConfig, defaultConfig, resolveEndpoint, getApiKey } from '../config.js';
+import { ApiError, retryTransient, retryAfterMsFromResponse } from '../api.js';
 import { safeFetch } from '../util/security.js';
+import { authHeaders } from '../util/authHeaders.js';
 export async function whoamiCommand() {
-    const config = await loadConfig();
+    // Config is optional for `whoami` — a brand-new user runs it before `init`
+    // to verify their key works at all. Mirror the same fallback `login` uses.
+    let config;
+    try {
+        config = await loadConfig();
+    }
+    catch {
+        config = { ...defaultConfig };
+    }
     // Ask for a full page (server caps at 1000) so `count` is honest for any
     // project with ≤1000 assets — the previous `limit=1` always reported "1+".
     const url = new URL(`${resolveEndpoint(config)}/manifest`);
     url.searchParams.set('limit', '1000');
-    const res = await safeFetch(url.href, {
-        headers: { Authorization: `Bearer ${getApiKey()}`, 'User-Agent': CLI_USER_AGENT },
+    // Wrap in retryTransient so a transient 503 / network blip doesn't make
+    // `whoami` falsely report "key rejected" — the same recovery the rest of
+    // the API surface gets.
+    const result = await retryTransient('whoami', async () => {
+        const { headers, requestId } = authHeaders(getApiKey());
+        const res = await safeFetch(url.href, { headers });
+        const serverRequestId = res.headers.get('x-request-id') ?? requestId;
+        if (res.status === 401 || res.status === 403) {
+            await res.body?.cancel();
+            // Non-retryable: surface as a structured result rather than throwing,
+            // so retryTransient doesn't burn extra attempts on a hard rejection.
+            return { kind: 'rejected', status: res.status, serverRequestId };
+        }
+        if (res.status >= 500 || res.status === 429) {
+            const bodyText = await res.text();
+            // Pass Retry-After through so retryTransient honours server back-pressure
+            // (matches fetchManifestPage / fetchAssetBytes).
+            throw new ApiError(res.status, bodyText.slice(0, 200), serverRequestId, retryAfterMsFromResponse(res));
+        }
+        if (!res.ok) {
+            const bodyText = await res.text();
+            return { kind: 'error', status: res.status, bodyText, serverRequestId };
+        }
+        const raw = (await res.json());
+        // Shape-guard: mirror fetchManifestPage's contract so a malformed server
+        // body (e.g. items missing or not an array) reports cleanly instead of
+        // throwing TypeError on `body.items[0]?.key` below.
+        const body = {
+            count: typeof raw.count === 'number' && raw.count > 0 ? Math.floor(raw.count) : 0,
+            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 };
     });
-    if (res.status === 401 || res.status === 403) {
-        await res.body?.cancel();
-        console.log(kleur.red('✗ API key rejected (401/403).'));
+    if (result.kind === 'rejected') {
+        console.log(kleur.red(`✗ API key rejected (${result.status}).`));
         console.log(kleur.dim('  Generate a new key at MagicPixel → Settings → API Keys.'));
+        console.log(kleur.dim(`  (request id: ${result.serverRequestId})`));
         process.exitCode = 1;
         return;
     }
-    if (!res.ok) {
-        const body = await res.text();
-        console.log(kleur.red(`✗ ${res.status}: ${body.slice(0, 200)}`));
+    if (result.kind === 'error') {
+        console.log(kleur.red(`✗ ${result.status}: ${result.bodyText.slice(0, 200)}`));
+        console.log(kleur.dim(`  (request id: ${result.serverRequestId})`));
         process.exitCode = 1;
         return;
     }
-    const body = (await res.json());
+    const { body } = result;
     const more = body.nextCursor ? '+' : '';
     console.log(kleur.green('✓ key valid'));
     console.log(`  endpoint: ${resolveEndpoint(config)}`);

package/dist/config.js

@@ -1,8 +1,10 @@
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { readFile, mkdir, rename } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
-import { validateEndpointUrl } from './util/security.js';
+import { assertSafeOutDir, MAX_GLOB_LEN, validateEndpointUrl } from './util/security.js';
 import { readCredentialsSync } from './util/credentials.js';
+import { friendlyFsError } from './util/errors.js';
+import { atomicWrite } from './util/atomicWrite.js';
 const CONFIG_FILENAME = 'magicpixel.json';
 const STATE_DIR = '.magicpixel';
 const STATE_FILENAME = 'state.json';
@@ -34,11 +36,19 @@ export async function loadConfig(cwd = process.cwd()) {
         throw new Error(`${CONFIG_FILENAME} is not valid JSON: ${e.message}\n` +
             `  Fix: open the file and check for trailing commas or quotes.`);
     }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`${CONFIG_FILENAME} must be a JSON object (got ${Array.isArray(parsed) ? 'array' : typeof parsed}).\n` +
+            `  Fix: replace the file contents with { "outDir": "src/assets/magicpixel", "include": ["**/*"] }.`);
+    }
     const include = normalizeGlobList(parsed.include ?? defaultConfig.include, 'include');
     const exclude = normalizeGlobList(parsed.exclude ?? defaultConfig.exclude, 'exclude');
-    const outDir = typeof parsed.outDir === 'string' && parsed.outDir.trim() ? parsed.outDir.trim() : defaultConfig.outDir;
-    if (outDir.includes('\0') || outDir.split(/[/\\]/).some((seg) => seg === '..')) {
-        throw new Error(`${CONFIG_FILENAME}: outDir must not contain ".." segments.\n` +
+    const rawOutDir = typeof parsed.outDir === 'string' && parsed.outDir.trim() ? parsed.outDir : defaultConfig.outDir;
+    let outDir;
+    try {
+        outDir = assertSafeOutDir(rawOutDir);
+    }
+    catch (e) {
+        throw new Error(`${CONFIG_FILENAME}: ${e.message}\n` +
             `  Fix: use a path like src/assets/magicpixel.`);
     }
     let endpoint;
@@ -48,54 +58,112 @@ export async function loadConfig(cwd = process.cwd()) {
         }
         endpoint = validateEndpointUrl(parsed.endpoint.trim());
     }
+    let emitIndex = defaultConfig.emitIndex ?? true;
+    if (parsed.emitIndex !== undefined) {
+        if (typeof parsed.emitIndex !== 'boolean') {
+            throw new Error(`${CONFIG_FILENAME}: "emitIndex" must be a boolean (got ${typeof parsed.emitIndex}).\n` +
+                `  Fix: set "emitIndex": true or "emitIndex": false (or remove the field).`);
+        }
+        emitIndex = parsed.emitIndex;
+    }
     return {
         outDir,
         include,
         exclude,
         endpoint,
-        emitIndex: parsed.emitIndex ?? defaultConfig.emitIndex,
+        emitIndex,
     };
 }
 const MAX_GLOBS = 64;
-const MAX_GLOB_LEN = 256;
 function normalizeGlobList(value, field) {
     if (!Array.isArray(value)) {
-        throw new Error(`${CONFIG_FILENAME}: "${field}" must be an array of glob strings.`);
+        throw new Error(`${CONFIG_FILENAME}: "${field}" must be an array of glob strings (got ${typeof value}).\n` +
+            `  Fix: change "${field}" to an array, e.g. "${field}": ["**/*"].`);
     }
     if (value.length > MAX_GLOBS) {
-        throw new Error(`${CONFIG_FILENAME}: "${field}" has too many entries (max ${MAX_GLOBS}).`);
+        throw new Error(`${CONFIG_FILENAME}: "${field}" has too many entries (${value.length}, max ${MAX_GLOBS}).\n` +
+            `  Fix: combine patterns or split your sync into multiple projects.`);
     }
     const out = [];
     for (const item of value) {
         if (typeof item !== 'string' || !item.trim()) {
-            throw new Error(`${CONFIG_FILENAME}: "${field}" entries must be non-empty strings.`);
+            throw new Error(`${CONFIG_FILENAME}: "${field}" entries must be non-empty strings.\n` +
+                `  Fix: remove empty/null entries from "${field}".`);
         }
         const g = item.trim();
         if (g.length > MAX_GLOB_LEN || g.includes('\0')) {
-            throw new Error(`${CONFIG_FILENAME}: "${field}" entry is too long or invalid.`);
+            throw new Error(`${CONFIG_FILENAME}: "${field}" entry is too long (>${MAX_GLOB_LEN} chars) or contains a null byte.\n` +
+                `  Fix: shorten the pattern.`);
         }
         out.push(g);
     }
     return out;
 }
 export async function saveConfig(config, cwd = process.cwd()) {
-    await writeFile(configPath(cwd), JSON.stringify(config, null, 2) + '\n', 'utf8');
+    const path = configPath(cwd);
+    try {
+        // Atomic write: a crash mid-write must never leave magicpixel.json
+        // truncated — a corrupt config wedges every subsequent `sync`/`status`
+        // run with a JSON parse error and is exactly the scenario `repair` was
+        // built to recover from. Cheap to avoid in the first place.
+        await atomicWrite(path, JSON.stringify(config, null, 2) + '\n');
+    }
+    catch (e) {
+        throw friendlyFsError(e, {
+            operation: 'Saving magicpixel.json',
+            path,
+            hint: 'magicpixel.json holds your sync config — without it `magicpixel sync` can\'t run.',
+        });
+    }
 }
 export async function loadState(cwd = process.cwd()) {
     const path = statePath(cwd);
     if (!existsSync(path))
         return {};
+    let raw;
     try {
-        return JSON.parse(await readFile(path, 'utf8'));
+        raw = await readFile(path, 'utf8');
     }
     catch {
         return {};
     }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        // Corrupt state file (truncated by a crash, hand-edited, disk full, etc.)
+        // Quarantine it so the user can recover/inspect, then fall back to a full
+        // re-sync rather than wedging every future run with a parse error.
+        const quarantine = `${path}.corrupt-${Date.now()}`;
+        try {
+            await rename(path, quarantine);
+            console.warn(`[magicpixel] state.json was corrupt (${e.message}). ` +
+                `Moved to ${quarantine} and falling back to a full sync.`);
+        }
+        catch {
+            console.warn(`[magicpixel] state.json was corrupt (${e.message}); ` +
+                `falling back to a full sync.`);
+        }
+        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', { encoding: 'utf8', mode: 0o600 });
+    try {
+        await mkdir(dirname(path), { recursive: true });
+        // Atomic write: stage to a sibling tmp file then rename. Prevents a half-
+        // written state.json on crash/power-loss, which would then poison the next
+        // run (and require the corrupt-state recovery path above). Mode 0600
+        // because state.json sits next to the API-key-bearing credentials file.
+        await atomicWrite(path, JSON.stringify(state, null, 2) + '\n', { mode: 0o600 });
+    }
+    catch (e) {
+        throw friendlyFsError(e, {
+            operation: 'Saving sync state',
+            path,
+            hint: 'state.json tracks what was last synced — without it the next run re-downloads everything.',
+        });
+    }
 }
 export function resolveEndpoint(config) {
     if (config.endpoint)
@@ -111,13 +179,10 @@ export function resolveEndpoint(config) {
 export function getApiKey() {
     const fromEnv = process.env.MAGICPIXEL_API_KEY;
     let key = fromEnv;
-    let source = 'env';
     if (!key) {
         const stored = readCredentialsSync();
-        if (stored) {
+        if (stored)
             key = stored.apiKey;
-            source = 'credentials-file';
-        }
     }
     if (!key) {
         throw new Error('No MagicPixel API key found.\n' +
@@ -126,8 +191,11 @@ export function getApiKey() {
             '    2. Run `magicpixel login` (or `export MAGICPIXEL_API_KEY=mp_live_...`).\n' +
             '    3. Re-run the command.');
     }
+    // Env vars from shells routinely smuggle in stray quotes / whitespace; the
+    // credentials file is already trimmed at write time but we trim defensively
+    // here so both code paths share the same validation.
     const trimmed = key.trim();
-    if (trimmed !== key && source === 'env') {
+    if (trimmed !== key && fromEnv !== undefined) {
         throw new Error(`MAGICPIXEL_API_KEY has leading/trailing whitespace.\n` +
             `  Fix: export the key without spaces or quotes.`);
     }

package/dist/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { Command, InvalidArgumentError } from 'commander';
+import { Command } from 'commander';
 import kleur from 'kleur';
 import { initCommand } from './commands/init.js';
 import { syncCommand } from './commands/sync.js';
@@ -11,7 +11,9 @@ 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 { repairCommand } from './commands/repair.js';
 import { startCommand } from './commands/start.js';
+import { parseWatchInterval, parseConcurrency } from './util/flagValidators.js';
 import { CLI_VERSION } from './version.js';
 // Node version guard
 const major = Number(process.versions.node.split('.')[0]);
@@ -24,75 +26,88 @@ program
     .name('magicpixel')
     .description('Sync MagicPixel pixel-art assets to your local project')
     .version(CLI_VERSION);
-const wrap = (fn) => async (...args) => {
+const wrap = (commandName, fn) => async (...args) => {
     try {
         await fn(...args);
     }
     catch (e) {
-        const msg = e.message ?? String(e);
+        const err = e;
+        const msg = err.message ?? String(e);
         // Multi-line messages are already formatted with "Fix:" hints — print as-is.
         console.error(kleur.red(msg));
-        process.exit(1);
+        // Fire-and-forget telemetry → exit 1. `reportAndExit` decides whether
+        // the error is worth surfacing on /admin/errors (5xx ApiErrors +
+        // unexpected throws); user-fixable errors are filtered out inside
+        // `shouldReportCliError`. Lazy-imported so cold paths (e.g. `--help`)
+        // don't pay the cost.
+        const { reportAndExit } = await import('./util/telemetry.js');
+        await reportAndExit(err, commandName, 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)));
+    .action(wrap("start", 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)));
+    .action(wrap("init", 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)));
+    .action(wrap("login", async (opts) => loginCommand(opts)));
 program
     .command('logout')
     .description('Remove the stored MagicPixel API key')
-    .action(wrap(async () => logoutCommand()));
+    .action(wrap("logout", async () => logoutCommand()));
 program
     .command('doctor')
     .description('Print a single-page diagnostic to paste to your AI agent')
-    .action(wrap(async () => doctorCommand()));
+    .option('--json', 'Emit a stable JSON report (pipeable into jq or an LLM)')
+    .option('--offline', 'Skip the live manifest probe (useful behind a strict proxy)')
+    .addHelpText('after', '\nExamples:\n  $ magicpixel doctor\n  $ magicpixel doctor --json | jq .network\n')
+    .action(wrap("doctor", async (opts) => doctorCommand(opts)));
+program
+    .command('repair')
+    .description('Self-heal a broken sync: validate key, reset state, re-sync')
+    .option('--dry-run', 'Print the plan without writing files')
+    .option('-y, --yes', 'Skip the confirmation prompt before resetting state')
+    .addHelpText('after', '\nExamples:\n  $ magicpixel repair --dry-run    # see what would change\n  $ magicpixel repair --yes        # non-interactive recovery\n')
+    .action(wrap("repair", async (opts) => repairCommand(opts)));
 program
     .command('sync')
     .description('Download changed assets from MagicPixel')
     .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)
+    .option('-w, --watch [seconds]', 'Poll for changes (default 2s; auto-slows to 5s after ~3min idle, 10s after ~15min)', parseWatchInterval)
     .option('-q, --quiet', 'Minimal output (for CI)')
-    .option('-c, --concurrency <n>', 'Parallel downloads (1–16, default 6)', (v) => {
-    const n = parseInt(v, 10);
-    if (!Number.isFinite(n) || String(n) !== v.trim() || n < 1 || n > 16) {
-        throw new InvalidArgumentError(`expected an integer 1–16, got "${v}".`);
-    }
-    return n;
-})
-    .action(wrap(async (opts) => syncCommand(opts)));
+    .option('-c, --concurrency <n>', 'Parallel downloads (1–16, default 6)', parseConcurrency)
+    .addHelpText('after', '\nExamples:\n  $ magicpixel sync                # incremental sync\n  $ magicpixel sync --full         # ignore lastSync, re-check everything\n  $ magicpixel sync -w             # watch mode (2s; adaptive idle backoff; exit 2 after 5 auth failures)\n')
+    .action(wrap("sync", async (opts) => syncCommand(opts)));
 program
     .command('add <glob>')
     .description('Append a glob pattern to include')
-    .action(wrap(async (glob) => addCommand(glob)));
+    .action(wrap("add", async (glob) => addCommand(glob)));
 program
     .command('remove <glob>')
     .description('Remove a glob pattern from include')
-    .action(wrap(async (glob) => removeCommand(glob)));
+    .action(wrap("remove", async (glob) => removeCommand(glob)));
 program
     .command('list')
     .description('List the matching assets in the manifest')
-    .action(wrap(async () => listCommand()));
+    .addHelpText('after', '\nExamples:\n  $ magicpixel list                # tabular preview of every matching asset\n  $ magicpixel list | head         # quick sanity-check after editing include globs\n')
+    .action(wrap("list", async () => listCommand()));
 program
     .command('status')
     .description('Show config, last sync, and diff vs remote')
-    .action(wrap(async () => statusCommand()));
+    .action(wrap("status", async () => statusCommand()));
 program
     .command('whoami')
     .description('Verify the API key and show what it can see')
-    .action(wrap(async () => whoamiCommand()));
+    .action(wrap("whoami", async () => whoamiCommand()));
 program.parseAsync(process.argv);

package/dist/util/atomicWrite.js

@@ -0,0 +1,25 @@
+import { writeFile, rename, chmod } from 'node:fs/promises';
+import { tmpPathFor } from './security.js';
+/**
+ * Stage-and-rename file write. A crash mid-write can never leave a truncated
+ * file on disk — the rename is atomic on every POSIX FS and on NTFS. Used
+ * everywhere a corrupted target would break the project (state.json,
+ * package.json, magicpixel.json, credentials, AGENTS.md, generated index files).
+ */
+export async function atomicWrite(path, contents, opts = {}) {
+    const tmp = tmpPathFor(path);
+    const writeOpts = opts.mode !== undefined ? { encoding: 'utf8', mode: opts.mode } : 'utf8';
+    await writeFile(tmp, contents, writeOpts);
+    if (opts.mode !== undefined) {
+        // Belt-and-suspenders: writeFile's `mode` only applies on create. If the
+        // tmp path was somehow pre-existing (collision is vanishingly unlikely
+        // given the pid+random suffix) the chmod ensures the perms land.
+        try {
+            await chmod(tmp, opts.mode);
+        }
+        catch {
+            // Windows / read-only FS — ignore.
+        }
+    }
+    await rename(tmp, path);
+}

package/dist/util/auth.js

@@ -0,0 +1,41 @@
+import { resolveEndpoint } from '../config.js';
+import { ApiError, retryTransient } from '../api.js';
+import { safeFetch, readBodyWithLimit } from './security.js';
+import { authHeaders } from './authHeaders.js';
+/**
+ * Validate an API key against `/manifest?limit=1`. Throws a friendly error on
+ * rejection / network failure; resolves silently on success. Used by `login`
+ * (post-prompt) and `repair` (step 1).
+ *
+ * Wrapped in `retryTransient` so a single 503 or network blip during
+ * onboarding doesn't kick the user back to "paste your key again". Carries
+ * `X-Request-Id` so a rejection is grep-able in the edge function logs
+ * (mem://integration/cli-request-id-contract).
+ */
+export async function assertKeyValid(key, config) {
+    const url = new URL(`${resolveEndpoint(config)}/manifest`);
+    url.searchParams.set('limit', '1');
+    await retryTransient('validate key', async () => {
+        const { headers, requestId } = authHeaders(key);
+        const res = await safeFetch(url.href, { headers });
+        const serverRequestId = res.headers.get('x-request-id') ?? requestId;
+        if (res.status === 401 || res.status === 403) {
+            await res.body?.cancel();
+            // 4xx auth — non-retryable. Throw as ApiError so retryTransient bubbles
+            // immediately rather than burning two extra attempts.
+            throw new ApiError(res.status, `Key was rejected (${res.status}). Generate a fresh one at https://magicpixel.art/settings.\n` +
+                `  (request id: ${serverRequestId})`, serverRequestId);
+        }
+        if (!res.ok) {
+            // Cap body read so a misbehaving endpoint returning a multi-MB error
+            // page can't balloon CLI memory. 16 KB is plenty for the 120-char slice
+            // we ultimately surface.
+            const bodyBytes = await readBodyWithLimit(res, 16 * 1024).catch(() => new Uint8Array());
+            const body = new TextDecoder().decode(bodyBytes);
+            // 5xx + 429 retry through retryTransient; other 4xx bubble immediately.
+            throw new ApiError(res.status, `Server returned ${res.status}: ${body.slice(0, 120)}\n` +
+                `  (request id: ${serverRequestId})`, serverRequestId);
+        }
+        await res.body?.cancel();
+    });
+}

package/dist/util/authHeaders.js

@@ -0,0 +1,24 @@
+import { randomUUID } from 'node:crypto';
+import { CLI_USER_AGENT } from '../version.js';
+/**
+ * Build the standard request-header bundle used by every CLI → API call.
+ * Enforces the cross-cutting contract documented in
+ * mem://integration/cli-request-id-contract: every request carries a fresh
+ * `X-Request-Id` so the edge function can echo it back and support can
+ * correlate any failure against the edge function logs in one grep.
+ *
+ * Single shared helper instead of inlining the same three headers at every
+ * call site (`api.ts`, `auth.ts`, `whoami.ts`, `doctor.ts`).
+ */
+export function authHeaders(apiKey, extra) {
+    const requestId = randomUUID();
+    return {
+        requestId,
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            'User-Agent': CLI_USER_AGENT,
+            'X-Request-Id': requestId,
+            ...extra,
+        },
+    };
+}

package/dist/util/credentials.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
-import { mkdir, readFile, writeFile, unlink, chmod } from 'node:fs/promises';
+import { mkdir, readFile, unlink } from 'node:fs/promises';
 import { resolve, dirname } from 'node:path';
+import { atomicWrite } from './atomicWrite.js';
 const CREDENTIALS_DIR = '.magicpixel';
 const CREDENTIALS_FILE = 'credentials';
 export function credentialsPath(cwd = process.cwd()) {
@@ -27,14 +28,10 @@ export async function writeCredentials(apiKey, cwd = process.cwd()) {
     const path = credentialsPath(cwd);
     await mkdir(dirname(path), { recursive: true });
     const body = { apiKey: apiKey.trim(), savedAt: new Date().toISOString() };
-    await writeFile(path, JSON.stringify(body, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
-    // Belt-and-suspenders: chmod again in case the file pre-existed with looser perms.
-    try {
-        await chmod(path, 0o600);
-    }
-    catch {
-        // ignore (Windows or read-only FS)
-    }
+    // Atomic stage-and-rename. The mode is applied to the tmp file *before* the
+    // rename so the final credentials file is never world-readable for even a
+    // single tick (crash-window safety + perm-window safety in one call).
+    await atomicWrite(path, JSON.stringify(body, null, 2) + '\n', { mode: 0o600 });
     return path;
 }
 export async function deleteCredentials(cwd = process.cwd()) {
@@ -62,7 +59,10 @@ export async function findKeyInDotenv(cwd = process.cwd()) {
         try {
             const raw = await readFile(path, 'utf8');
             for (const line of raw.split('\n')) {
-                const m = line.match(/^\s*MAGICPIXEL_API_KEY\s*=\s*"?([^"\n#]+?)"?\s*$/);
+                // Anchored on the *exact* key name — otherwise `MAGICPIXEL_API_KEY_OLD`
+                // or `MAGICPIXEL_API_KEY_BACKUP` would silently match and return the
+                // wrong value. Allows optional `export` prefix and spaces around `=`.
+                const m = line.match(/^\s*(?:export\s+)?MAGICPIXEL_API_KEY\s*=\s*"?([^"\n#]+?)"?\s*(?:#.*)?$/);
                 if (m && m[1])
                     return { file: name, value: m[1].trim() };
             }
@@ -80,3 +80,20 @@ export function describeKeySource(cwd = process.cwd()) {
         return 'credentials-file';
     return 'none';
 }
+/**
+ * Best-effort read of the API key for *display only* (e.g. `status`,
+ * `doctor`). Honors the same precedence as `getApiKey()` but never throws and
+ * never validates — callers that need a real key should still use `getApiKey`.
+ *
+ * Returns `null` when no key is configured. The caller is responsible for
+ * masking before printing.
+ */
+export function readKeyForDisplay(cwd = process.cwd()) {
+    const fromEnv = process.env.MAGICPIXEL_API_KEY?.trim();
+    if (fromEnv)
+        return { value: fromEnv, source: 'env' };
+    const stored = readCredentialsSync(cwd);
+    if (stored)
+        return { value: stored.apiKey, source: 'credentials-file' };
+    return null;
+}