@magicpixelart/cli 0.3.3 → 0.5.0

package/dist/api.js

@@ -1,16 +1,29 @@
-import { resolveEndpoint, getApiKey, CLI_USER_AGENT, CLI_VERSION } from './config.js';
+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';
+/**
+ * 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) —
+ * surface it in user messages so support can correlate against edge logs.
+ *
+ * `retryAfterMs` is populated when the server sent a `Retry-After` header on
+ * a 429/5xx; the retry helper honors it instead of the default backoff.
+ */
 export class ApiError extends Error {
     status;
-    constructor(status, message) {
+    requestId;
+    retryAfterMs;
+    constructor(status, message, requestId, retryAfterMs) {
         super(message);
         this.status = status;
+        this.requestId = requestId;
+        this.retryAfterMs = retryAfterMs;
     }
 }
 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.`);
+            `  Fix: regenerate at https://magicpixel.art/settings and re-run \`magicpixel login\`.`);
     }
     if (status === 404) {
         return (`${context}: 404 — endpoint or asset not found.\n` +
@@ -24,11 +37,19 @@ function friendly(status, body, context) {
     }
     return `${context}: ${status} — ${body.slice(0, 200)}`;
 }
-function authHeaders() {
-    return {
-        Authorization: `Bearer ${getApiKey()}`,
-        'User-Agent': CLI_USER_AGENT,
-    };
+/** Append "(request id: …)" to a friendly message — only when we have one. */
+function withRequestId(message, requestId) {
+    if (!requestId)
+        return message;
+    return `${message}\n  (request id: ${requestId})`;
+}
+/**
+ * Authenticated header bundle for API requests. Re-reads `getApiKey()` on
+ * every call so a `magicpixel login` in another terminal is picked up by the
+ * next retry tick of a long-running `sync --watch`.
+ */
+function buildHeaders(extra) {
+    return authHeaders(getApiKey(), extra);
 }
 export async function fetchManifestPage(opts) {
     const url = new URL(`${resolveEndpoint(opts.config)}/manifest`);
@@ -42,22 +63,75 @@ export async function fetchManifestPage(opts) {
         url.searchParams.set('cursor', opts.cursor);
     if (opts.limit)
         url.searchParams.set('limit', String(opts.limit));
-    let res;
-    try {
-        res = await safeFetch(url.href, { 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'));
+    // Reuse the same transient-failure policy as asset downloads: 3 attempts,
+    // exponential backoff, honor Retry-After on 429/5xx. Network blips and
+    // brief edge restarts otherwise blow up the whole sync mid-pagination.
+    return retryTransient(`manifest`, async () => {
+        const { headers, requestId } = buildHeaders();
+        const res = await safeFetch(url.href, { headers });
+        const serverRequestId = res.headers.get('x-request-id') ?? requestId;
+        if (res.status >= 200 && res.status < 300) {
+            const minCli = res.headers.get('x-magicpixel-min-cli-version');
+            if (minCli)
+                maybeWarnStaleCli(minCli);
+            const data = (await res.json());
+            // Shape-guard the response. A malformed edge response (null,
+            // {items: null}, nextCursor: 42, etc.) would otherwise either crash
+            // inside the pagination loop ("null is not iterable") or get fed back
+            // as a bogus ?cursor=42 on the next request. Surface a friendly
+            // ApiError carrying the request id so support can grep the edge logs.
+            const isObject = !!data && typeof data === 'object' && !Array.isArray(data);
+            const cursor = isObject ? data.nextCursor : undefined;
+            const cursorOk = cursor === null || cursor === undefined || typeof cursor === 'string';
+            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);
+            }
+            return data;
+        }
+        const bodyText = await res.text();
+        throw new ApiError(res.status, withRequestId(friendly(res.status, bodyText, 'manifest'), serverRequestId), serverRequestId, retryAfterMsFromResponse(res));
+    });
+}
+/**
+ * Run `fn` up to 3 times, backing off on network errors, 429, and 5xx.
+ * Non-retryable ApiErrors (4xx other than 429) bubble immediately.
+ *
+ * - `ApiError.retryAfterMs` (populated from a `Retry-After` header on 429/5xx)
+ *   wins over the default exponential backoff for the *next* attempt.
+ * - Network/transport failures are wrapped once with a friendly hint and the
+ *   request-id of the most recent attempt.
+ */
+export async function retryTransient(context, fn) {
+    const maxAttempts = 3;
+    let lastErr = null;
+    let nextDelayMs = 0;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (e) {
+            const err = e;
+            if (err instanceof ApiError) {
+                if (err.status < 500 && err.status !== 429)
+                    throw err;
+                lastErr = err;
+                nextDelayMs = err.retryAfterMs ?? 0;
+            }
+            else {
+                // Network/transport failure — wrap once with the existing hint.
+                // Preserve the original error as `cause` so `--verbose` consumers
+                // and Node's default printer can still surface the underlying stack.
+                lastErr = new Error(`${context}: network error (${err.message}).\n` +
+                    `  Fix: check your internet connection and that the MagicPixel API is reachable.`, { cause: err });
+                nextDelayMs = 0;
+            }
+            if (attempt < maxAttempts) {
+                const backoffMs = 250 * 2 ** (attempt - 1);
+                await new Promise((r) => setTimeout(r, Math.max(nextDelayMs, backoffMs)));
+            }
+        }
     }
-    // Hint to nudge stale CLIs. Printed once per process by sync.ts.
-    const minCli = res.headers.get('x-magicpixel-min-cli-version');
-    if (minCli)
-        maybeWarnStaleCli(minCli);
-    return (await res.json());
+    throw lastErr ?? new Error(`${context}: unknown error`);
 }
 // ----- Stale-CLI nudge ------------------------------------------------------
 // Cheap version comparison: split on dots, compare numerically. Pre-release
@@ -79,6 +153,10 @@ function maybeWarnStaleCli(minVersion) {
     console.warn(`\n[magicpixel] CLI ${current} is older than the recommended ${min}.\n` +
         `  Fix: npm i -D @magicpixelart/cli@latest (or @magicpixelart/vite)\n`);
 }
+/** Test-only: reset the module-singleton warn-once flag between vitest runs. */
+export function __resetStaleWarnedForTesting() {
+    staleWarned = false;
+}
 function compareSemver(a, b) {
     const pa = a.split('.').map((n) => parseInt(n, 10) || 0);
     const pb = b.split('.').map((n) => parseInt(n, 10) || 0);
@@ -98,75 +176,60 @@ export async function fetchAllManifest(config, since) {
     for (let page = 0; page < MAX_PAGES; page++) {
         const res = await fetchManifestPage({ config, since, cursor, limit: 500 });
         out.push(...res.items);
-        cursor = res.nextCursor ?? undefined;
-        if (!cursor)
+        const nextCursor = res.nextCursor ?? undefined;
+        if (!nextCursor)
             return out;
+        // Detect a stuck cursor (server returns the same token it just received)
+        // in O(1) round-trips instead of burning the full page budget.
+        if (nextCursor === cursor) {
+            throw new Error(`manifest: server returned a repeating cursor — possible server cursor loop.\n` +
+                `  Fix: re-run with --full, or report at https://github.com/magicpixel/cli/issues.`);
+        }
+        cursor = nextCursor;
     }
     throw new Error(`manifest: pagination exceeded ${MAX_PAGES} pages — possible server cursor loop.\n` +
         `  Fix: re-run with --full, or report at https://github.com/magicpixel/cli/issues.`);
 }
 /**
  * Download a single asset by key. Returns null on 304 (not modified).
- * Retries transient failures (network errors, 429, 5xx) with backoff.
+ * Shares the retryTransient policy with manifest fetches — including
+ * Retry-After honoring and request-id propagation on failures.
  */
 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'] = etagForSha256(knownSha);
-    const maxAttempts = 3;
-    let lastErr = null;
-    let retryAfterMs = 0; // populated from Retry-After when present
-    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-        try {
-            const res = await safeFetch(url.href, { headers });
-            if (res.status === 304) {
-                // Drain so undici can return the socket to the keep-alive pool.
-                await res.body?.cancel();
-                return null;
-            }
-            if (res.ok)
-                return await readBodyWithLimit(res, MAX_ASSET_BYTES);
-            // Consume the body via .text() for the error message; this also drains
-            // the stream so we don't leak the socket on retry.
-            const bodyText = await res.text();
-            if (res.status === 429 || res.status >= 500) {
-                // Honor Retry-After (seconds). Cap at 60s so a bogus header can't hang
-                // the CLI; fall back to exponential backoff when missing/invalid.
-                const ra = parseRetryAfterSeconds(res.headers.get('retry-after'));
-                if (ra > 0)
-                    retryAfterMs = Math.min(ra * 1000, 60_000);
-                lastErr = new ApiError(res.status, friendly(res.status, bodyText, `download ${key}`));
-            }
-            else {
-                throw new ApiError(res.status, friendly(res.status, bodyText, `download ${key}`));
-            }
-        }
-        catch (e) {
-            lastErr = e;
-            if (e instanceof ApiError && e.status < 500 && e.status !== 429)
-                throw e;
+    const conditional = knownSha ? { 'If-None-Match': etagForSha256(knownSha) } : undefined;
+    return retryTransient(`download ${key}`, async () => {
+        const { headers, requestId } = buildHeaders(conditional);
+        const res = await safeFetch(url.href, { headers });
+        const serverRequestId = res.headers.get('x-request-id') ?? requestId;
+        if (res.status === 304) {
+            // Drain so undici can return the socket to the keep-alive pool.
+            await res.body?.cancel();
+            return null;
         }
-        if (attempt < maxAttempts) {
-            const backoffMs = 250 * 2 ** (attempt - 1);
-            await new Promise((r) => setTimeout(r, Math.max(retryAfterMs, backoffMs)));
-            retryAfterMs = 0;
-        }
-    }
-    throw lastErr ?? new Error(`download ${key}: unknown error`);
+        if (res.ok)
+            return await readBodyWithLimit(res, MAX_ASSET_BYTES);
+        const bodyText = await res.text();
+        throw new ApiError(res.status, withRequestId(friendly(res.status, bodyText, `download ${key}`), serverRequestId), serverRequestId, retryAfterMsFromResponse(res));
+    });
 }
-/** Retry-After may be seconds or an HTTP-date (RFC 7231). Accept both. */
-function parseRetryAfterSeconds(raw) {
+/**
+ * Parse a `Retry-After` header (seconds or HTTP-date per RFC 7231) into ms.
+ * Capped at 60s so a bogus header can't hang the CLI. Returns 0 when absent
+ * or invalid (caller falls back to its default backoff).
+ */
+export function retryAfterMsFromResponse(res) {
+    const raw = res.headers.get('retry-after');
     if (!raw)
         return 0;
     const trimmed = raw.trim();
     const n = Number(trimmed);
     if (Number.isFinite(n) && n > 0)
-        return n;
+        return Math.min(n * 1000, 60_000);
     const asDate = Date.parse(trimmed);
     if (!Number.isNaN(asDate)) {
-        return Math.max(0, Math.ceil((asDate - Date.now()) / 1000));
+        return Math.min(Math.max(0, asDate - Date.now()), 60_000);
     }
     return 0;
 }

package/dist/commands/doctor.js

@@ -3,54 +3,42 @@ import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { resolve, relative } from 'node:path';
 import { loadConfig, loadState, resolveEndpoint, defaultConfig } from '../config.js';
-import { describeKeySource } from '../util/credentials.js';
+import { describeKeySource, readKeyForDisplay } from '../util/credentials.js';
 import { detectFramework, hasPackageJson } from '../util/framework.js';
+import { safeFetch } from '../util/security.js';
+import { authHeaders } from '../util/authHeaders.js';
 import { CLI_VERSION } from '../version.js';
+export async function doctorCommand(opts = {}) {
+    const report = await collectDoctorReport(opts);
+    if (opts.json) {
+        // Pure JSON to stdout — no ANSI, no header. Pipe-able into `jq` or pasted
+        // into an LLM verbatim.
+        process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+        return;
+    }
+    console.log(renderDoctorReport(report));
+}
 /**
- * Single-page diagnostic that a non-technical user can paste to their AI agent
- * when something breaks. Read-only — never mutates state or hits the network.
+ * Read-only data collection. Hits the network exactly once (a HEAD-equivalent
+ * GET against `/manifest?limit=1`) unless `--offline` is set. Never mutates
+ * state on disk.
  */
-export async function doctorCommand() {
-    const lines = [];
-    const push = (s = '') => lines.push(s);
-    push(kleur.bold('MagicPixel CLI — doctor'));
-    push(kleur.dim(`  Paste this to your AI agent if something isn't working.`));
-    push();
-    push(`CLI version:        ${CLI_VERSION}`);
-    push(`Node version:       ${process.versions.node}`);
-    push(`Platform:           ${process.platform}`);
-    push(`cwd:                ${process.cwd()}`);
-    push();
-    // Framework + package.json
+export async function collectDoctorReport(opts = {}) {
     const framework = await detectFramework();
-    push(`package.json:       ${hasPackageJson() ? 'found' : kleur.yellow('missing')}`);
-    push(`Framework detected: ${framework ?? kleur.dim('none')}`);
-    // Config
+    const pkgFound = hasPackageJson();
     let config = null;
+    let configErr = null;
     try {
         config = await loadConfig();
-        push(`magicpixel.json:    found`);
-        push(`  outDir:           ${config.outDir}`);
-        push(`  emitIndex:        ${config.emitIndex === false ? 'false' : 'true'}`);
-        push(`  include:          ${config.include.join(', ')}`);
-        if (config.exclude.length)
-            push(`  exclude:          ${config.exclude.join(', ')}`);
-        if (config.endpoint)
-            push(`  endpoint:         ${kleur.yellow(config.endpoint)} (custom)`);
     }
     catch (e) {
-        push(`magicpixel.json:    ${kleur.yellow('missing')} (${e.message.split('\n')[0]})`);
+        // Preserve the full multi-line "Fix:" hint for `--json` consumers (LLM
+        // paste-and-debug). The human renderer below trims to the first line so
+        // the TTY layout stays compact.
+        configErr = e.message;
     }
-    push(`API endpoint:       ${resolveEndpoint(config ?? { ...defaultConfig })}`);
-    // Key source
+    const endpoint = resolveEndpoint(config ?? { ...defaultConfig });
     const keySource = describeKeySource();
-    const sourceLabel = keySource === 'env'
-        ? 'environment variable (MAGICPIXEL_API_KEY)'
-        : keySource === 'credentials-file'
-            ? '.magicpixel/credentials'
-            : kleur.yellow('none — run `magicpixel login`');
-    push(`API key source:     ${sourceLabel}`);
-    // Watch script
     let watchScript = null;
     try {
         const pkgPath = resolve(process.cwd(), 'package.json');
@@ -60,33 +48,190 @@ export async function doctorCommand() {
         }
     }
     catch {
-        // ignore
+        // package.json absent or unreadable — already reflected in `hasPackageJson`.
     }
-    push(`Watch script:       ${watchScript ? `"${watchScript}"` : kleur.dim('not configured')}`);
-    // State
     const state = await loadState();
-    push(`Last sync:          ${state.lastSync ? new Date(state.lastSync).toLocaleString() : kleur.dim('never')}`);
-    push(`Assets in state:    ${state.assets ? Object.keys(state.assets).length : 0}`);
-    if (state.lastError)
-        push(`Last error:         ${kleur.yellow(state.lastError)}`);
-    // outDir contents (approximate)
+    let outDirPath = null;
+    let outDirExists = false;
     if (config) {
-        const out = resolve(process.cwd(), config.outDir);
-        if (existsSync(out)) {
-            push(`outDir on disk:     ${relative(process.cwd(), out)} (exists)`);
+        const abs = resolve(process.cwd(), config.outDir);
+        outDirPath = relative(process.cwd(), abs) || config.outDir;
+        outDirExists = existsSync(abs);
+    }
+    // Skip the network probe when there's no key — it would unauthenticate to
+    // a guaranteed 401 and surface a misleading "API rejected the key"
+    // suggestion on top of the (correct) "run login" one. The network section
+    // still gets a structured value so `--json` consumers can branch on it.
+    const network = opts.offline
+        ? { skipped: 'offline' }
+        : keySource === 'none'
+            ? { skipped: 'no-api-key' }
+            : await probeManifest(endpoint);
+    const suggestions = [];
+    if (keySource === 'none')
+        suggestions.push('Run `magicpixel login` to store your API key.');
+    if (!config)
+        suggestions.push('Run `magicpixel start` (or `magicpixel init`) to bootstrap.');
+    if (config && !watchScript && pkgFound) {
+        suggestions.push('Add a `magicpixel:watch` npm script (or run `magicpixel sync -w`) for live sync.');
+    }
+    if (state.lastError)
+        suggestions.push('Last sync surfaced an error — run `magicpixel repair` to self-heal.');
+    // Only emit network-derived suggestions when we actually probed.
+    if ('ok' in network && !network.ok) {
+        if (network.status === 401 || network.status === 403) {
+            suggestions.push('API rejected the key — run `magicpixel login` with a fresh key from settings.');
+        }
+        else if (network.status === null) {
+            suggestions.push('Could not reach MagicPixel — check internet/proxy, or re-run with --offline.');
         }
         else {
-            push(`outDir on disk:     ${kleur.dim('not created yet')}`);
+            suggestions.push(`Manifest probe returned ${network.status} — paste the request id when filing a report.`);
         }
     }
+    return {
+        cli: CLI_VERSION,
+        node: process.versions.node,
+        platform: process.platform,
+        cwd: process.cwd(),
+        framework: framework ?? null,
+        hasPackageJson: pkgFound,
+        config: config
+            ? {
+                found: true,
+                outDir: config.outDir,
+                emitIndex: config.emitIndex !== false,
+                include: config.include,
+                exclude: config.exclude,
+                endpoint: config.endpoint ?? null,
+            }
+            : { found: false, error: configErr ?? 'unknown' },
+        endpoint,
+        key: { source: keySource },
+        watchScript,
+        state: {
+            lastSync: state.lastSync ?? null,
+            assetCount: state.assets ? Object.keys(state.assets).length : 0,
+            lastError: state.lastError ?? null,
+        },
+        outDir: { path: outDirPath, exists: outDirExists },
+        network,
+        suggestions,
+    };
+}
+async function probeManifest(endpoint) {
+    const url = new URL(`${endpoint}/manifest`);
+    url.searchParams.set('limit', '1');
+    const display = readKeyForDisplay();
+    if (!display) {
+        // Defensive: the caller in `collectDoctorReport` already returns the
+        // structured "no API key" record without invoking us. If we somehow get
+        // here, surface a clear internal error rather than a confusing 401.
+        return {
+            ok: false,
+            status: null,
+            roundtripMs: null,
+            requestId: null,
+            error: 'internal: probeManifest invoked without a stored API key',
+        };
+    }
+    const { headers, requestId } = authHeaders(display.value);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 5000);
+    const start = Date.now();
+    try {
+        const res = await safeFetch(url.href, { headers, signal: controller.signal });
+        await res.body?.cancel();
+        const elapsed = Date.now() - start;
+        const serverRequestId = res.headers.get('x-request-id') ?? requestId;
+        return {
+            ok: res.ok,
+            status: res.status,
+            roundtripMs: elapsed,
+            requestId: serverRequestId,
+            error: res.ok ? null : `HTTP ${res.status}`,
+        };
+    }
+    catch (e) {
+        return {
+            ok: false,
+            status: null,
+            roundtripMs: Date.now() - start,
+            requestId,
+            error: e.message,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Human-readable rendering of `DoctorReport`. */
+export function renderDoctorReport(r) {
+    const lines = [];
+    const push = (s = '') => lines.push(s);
+    push(kleur.bold('MagicPixel CLI — doctor'));
+    push(kleur.dim(`  Paste this to your AI agent if something isn't working.`));
     push();
-    push(kleur.dim('Next steps:'));
-    if (keySource === 'none')
-        push(kleur.dim('  • Run `magicpixel login` to store your API key.'));
-    if (!config)
-        push(kleur.dim('  • Run `magicpixel start` (or `magicpixel init`) to bootstrap.'));
-    if (!watchScript && hasPackageJson()) {
-        push(kleur.dim('  • Run `npm run magicpixel:watch` after init for live sync.'));
+    push(`CLI version:        ${r.cli}`);
+    push(`Node version:       ${r.node}`);
+    push(`Platform:           ${r.platform}`);
+    push(`cwd:                ${r.cwd}`);
+    push();
+    push(`package.json:       ${r.hasPackageJson ? 'found' : kleur.yellow('missing')}`);
+    push(`Framework detected: ${r.framework ?? kleur.dim('none')}`);
+    if (r.config.found) {
+        push(`magicpixel.json:    found`);
+        push(`  outDir:           ${r.config.outDir}`);
+        push(`  emitIndex:        ${r.config.emitIndex ? 'true' : 'false'}`);
+        push(`  include:          ${r.config.include.join(', ')}`);
+        if (r.config.exclude.length)
+            push(`  exclude:          ${r.config.exclude.join(', ')}`);
+        if (r.config.endpoint)
+            push(`  endpoint:         ${kleur.yellow(r.config.endpoint)} (custom)`);
+    }
+    else {
+        push(`magicpixel.json:    ${kleur.yellow('missing')} (${r.config.error.split('\n')[0]})`);
+    }
+    push(`API endpoint:       ${r.endpoint}`);
+    const sourceLabel = r.key.source === 'env'
+        ? 'environment variable (MAGICPIXEL_API_KEY)'
+        : r.key.source === 'credentials-file'
+            ? '.magicpixel/credentials'
+            : kleur.yellow('none — run `magicpixel login`');
+    push(`API key source:     ${sourceLabel}`);
+    push(`Watch script:       ${r.watchScript ? `"${r.watchScript}"` : kleur.dim('not configured')}`);
+    push(`Last sync:          ${r.state.lastSync ? new Date(r.state.lastSync).toLocaleString() : kleur.dim('never')}`);
+    push(`Assets in state:    ${r.state.assetCount}`);
+    if (r.state.lastError)
+        push(`Last error:         ${kleur.yellow(r.state.lastError)}`);
+    if (r.outDir.path !== null) {
+        push(`outDir on disk:     ${r.outDir.path} (${r.outDir.exists ? 'exists' : kleur.dim('not created yet')})`);
+    }
+    push();
+    if ('skipped' in r.network) {
+        const reason = r.network.skipped === 'offline'
+            ? 'skipped (--offline)'
+            : 'skipped (no API key — run `magicpixel login`)';
+        push(`Network probe:      ${kleur.dim(reason)}`);
+    }
+    else if (r.network.ok) {
+        push(`Network probe:      ${kleur.green('✓')} ${r.network.status} in ${r.network.roundtripMs}ms`);
+        if (r.network.requestId)
+            push(`  request id:       ${kleur.dim(r.network.requestId)}`);
+    }
+    else {
+        const statusLabel = r.network.status !== null ? `HTTP ${r.network.status}` : 'no response';
+        push(`Network probe:      ${kleur.red('✗')} ${statusLabel} (${r.network.roundtripMs}ms)`);
+        if (r.network.requestId)
+            push(`  request id:       ${kleur.dim(r.network.requestId)}`);
+        if (r.network.error)
+            push(`  error:            ${kleur.dim(r.network.error)}`);
+    }
+    if (r.suggestions.length > 0) {
+        push();
+        push(kleur.dim('Next steps:'));
+        for (const s of r.suggestions)
+            push(kleur.dim(`  • ${s}`));
     }
-    console.log(lines.join('\n'));
+    return lines.join('\n');
 }

package/dist/commands/init.js

@@ -1,11 +1,13 @@
 import kleur from 'kleur';
 import { existsSync } from 'node:fs';
-import { readFile, writeFile, appendFile } from 'node:fs/promises';
+import { readFile, appendFile, writeFile } 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';
-import { detectFramework, suggestOutDir, hasPackageJson } from '../util/framework.js';
+import { detectFramework, suggestOutDir, hasPackageJson, isStaticOutDir } from '../util/framework.js';
+import { assertSafeOutDir } from '../util/security.js';
+import { atomicWrite } from '../util/atomicWrite.js';
 const WATCH_SCRIPT_NAME = 'magicpixel:watch';
 const WATCH_SCRIPT_CMD = 'magicpixel sync --watch';
 export async function initCommand(opts) {
@@ -30,10 +32,24 @@ export async function initCommand(opts) {
             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;
+            // Re-prompt loop: catch unsafe outDir values (null bytes, `..` segments)
+            // at input time rather than letting `loadConfig` reject them on the next
+            // `sync`/`status` run. UX is faster and the error sits next to the cause.
+            // Delegates to `assertSafeOutDir` so the predicate matches `loadConfig` exactly.
+            for (;;) {
+                const ans = (await rl.question(`${kleur.cyan('?')} Where should assets be written? ${kleur.dim(`(${suggestedOutDir})`)} `)).trim();
+                const candidate = ans || suggestedOutDir;
+                try {
+                    config.outDir = assertSafeOutDir(candidate);
+                    break;
+                }
+                catch (e) {
+                    console.log(kleur.yellow(`  ${e.message} Try again.`));
+                }
+            }
             // 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)) {
+            if (!isStaticOutDir(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';
             }
@@ -53,7 +69,7 @@ export async function initCommand(opts) {
         }
     }
     else {
-        config.emitIndex = isImportableOutDir(config.outDir);
+        config.emitIndex = !isStaticOutDir(config.outDir);
     }
     await saveConfig(config);
     console.log();
@@ -111,22 +127,16 @@ async function ensureWatchScript(pkgPath) {
         scripts[WATCH_SCRIPT_NAME] = WATCH_SCRIPT_CMD;
         pkg.scripts = scripts;
         const trailingNewline = raw.endsWith('\n') ? '\n' : '';
-        await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + trailingNewline, 'utf8');
+        // Atomic write — a crash mid-write must never corrupt the user's package.json.
+        await atomicWrite(pkgPath, JSON.stringify(pkg, null, 2) + trailingNewline);
         return { added: true, alreadyPresent: false };
     }
     catch (e) {
         return { added: false, alreadyPresent: false, error: e.message };
     }
 }
-/**
- * `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);
-}
+// `isImportableOutDir` lives in util/framework.ts as `isStaticOutDir`
+// (negated) — shared with `emitIndex.ts`'s AGENTS.md snippet resolver.
 async function ensureGitignore() {
     const path = resolve(process.cwd(), '.gitignore');
     const marker = '.magicpixel/';