@magicpixelart/cli 0.1.2 → 0.3.0

package/README.md

@@ -14,36 +14,75 @@ Requires Node.js ≥ 18.
 
 ## Quickstart
 
+One command, inside your project folder (the one with `package.json`):
+
+```bash
+npx magicpixel start
+```
+
+That walks you through everything: detects your framework, writes `magicpixel.json`, prompts for your API key (paste it from [magicpixel.art/settings](https://magicpixel.art/settings) → API Keys), pulls your sprites, and tells you how to keep them fresh.
+
+When it finishes:
+
 ```bash
-npx magicpixel init          # interactive setup, detects your framework
-export MAGICPIXEL_API_KEY=mp_live_...
-npx magicpixel sync          # downloads changed assets
-npx magicpixel sync --watch  # keeps assets fresh while you work
+npm run magicpixel:watch        # keeps sprites fresh while you edit them in MagicPixel
 ```
 
-Get an API key at [magicpixel.art/settings](https://magicpixel.art/settings) → API Keys. Each key is bound to one project. Production keys are prefixed `mp_live_`; sandbox keys (used internally for tests) are prefixed `mp_test_` and accepted the same way.
+Production keys are prefixed `mp_live_`; sandbox keys (used internally for tests) are `mp_test_` and accepted the same way.
+
+### Where your key lives
+
+- **`MAGICPIXEL_API_KEY` env var** — highest priority, so CI keeps working with no code changes.
+- **`.magicpixel/credentials`** — written by `magicpixel login`, mode `0600`, automatically gitignored. This is what `start` uses for local dev.
+
+If `start` finds a `MAGICPIXEL_API_KEY` in your `.env` / `.env.local`, it offers to move it to the credentials file so it stops shipping in your bundler.
+
+### Manual setup (advanced)
+
+```bash
+npx magicpixel init           # writes magicpixel.json
+npx magicpixel login          # stores your key (or: export MAGICPIXEL_API_KEY=mp_live_...)
+npx magicpixel sync           # downloads changed assets
+npx magicpixel sync --watch   # keeps assets fresh while you work
+```
+
+### Something not working?
+
+```bash
+npx magicpixel doctor
+```
+
+Prints a one-screen diagnostic (CLI version, framework, outDir, key source, last sync, last error). Paste it to your AI agent — it's designed to be the only context they need.
 
-The key is read **only** from the `MAGICPIXEL_API_KEY` environment variable — never from `magicpixel.json` or any other file. This is intentional: it keeps secrets out of repos and CI logs.
 
 ## Typed asset index (default on)
 
 If `emitIndex` is true in `magicpixel.json`, every sync writes `<outDir>/index.ts`:
 
 ```ts
-import { MagicPixelAssets, type MagicPixelAssetKey } from '@/assets/magicpixel';
+import { MagicPixelAssets, MagicPixelAssetsById } from '@/assets/magicpixel';
 
+// Key-based: ergonomic, but breaks if you rename or move the asset in the editor.
 <img src={MagicPixelAssets['player/walk']} />
-// Typo? TypeScript error. Vite/webpack hash the URL at build time.
+
+// Id-based: survives every rename. Use for assets you don't want to chase imports for.
+<img src={MagicPixelAssetsById['abc123…']} />
 ```
 
+The index is built from what's actually on disk after each sync, so it can never disagree with the PNGs your bundler picks up. Renames are detected against the prior sync's snapshot — `sync` prints the old → new key plus the matching `MagicPixelAssetsById[...]` import hint so you can pick whichever you prefer.
+
 No bundler config, no runtime, no extra package.
 
 ## Commands
 
 | Command | What it does |
 | --- | --- |
-| `init [-y] [--force]` | Interactive config wizard. `-y` for CI. |
-| `sync [...flags]` | Fetch manifest, diff against disk, download changed assets. |
+| `start [--force]` | One-command bootstrap. Init + login + first sync. The only command to tell new users to run. |
+| `init [-y] [--force]` | Interactive config wizard. Offers a `magicpixel:watch` npm script. `-y` for CI. |
+| `login [--key <key>]` | Save your API key to `.magicpixel/credentials` (mode `0600`). Validates against the server first. |
+| `logout` | Remove the stored API key. |
+| `doctor` | Print a one-screen diagnostic — paste it to your AI agent when something breaks. |
+| `sync [...flags]` | Fetch manifest, diff against disk, download changed assets, prune orphans. |
 | `add <glob>` / `remove <glob>` | Manage `include` patterns. |
 | `list` | Print matching manifest as a table. |
 | `status` | Config, last sync, diff vs remote. |
@@ -54,12 +93,14 @@ No bundler config, no runtime, no extra package.
 | Flag | Meaning |
 | --- | --- |
 | `-w, --watch [seconds]` | Poll for changes (default 10s). Ideal during development. |
-| `--prune` | Delete local files no longer in the manifest. |
+| `--no-prune` | Keep local files not in the manifest (default: prune them on full syncs). |
 | `--dry-run` | Print plan, write nothing. |
 | `--full` | Ignore `lastSync`; re-fetch the full manifest. |
 | `-c, --concurrency <n>` | Parallel downloads (1–16, default 6). |
 | `-q, --quiet` | Minimal output (for CI). |
 
+Each successful sync prints a per-file change list (`+` added, `~` modified, `↪` renamed, `-` pruned) so you (and any AI agent reading the logs) know exactly what to wire up.
+
 Sync is built to be cheap: a no-op run is one small manifest request, zero PNG bytes.
 
 - sha256 diff against disk — matching files are never re-downloaded.
@@ -99,7 +140,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with: { node-version: 20 }
-      - run: npx -y @magicpixelart/cli sync --prune --quiet
+      - run: npx -y @magicpixelart/cli sync --quiet --full
         env:
           MAGICPIXEL_API_KEY: ${{ secrets.MAGICPIXEL_API_KEY }}
       - uses: peter-evans/create-pull-request@v6
@@ -123,7 +164,7 @@ Every error message includes a `Fix:` block. Common ones:
 
 | Symptom | Fix |
 | --- | --- |
-| `MAGICPIXEL_API_KEY is not set` | Export it from your shell. |
+| `No MagicPixel API key found` | Run `magicpixel login`, or `export MAGICPIXEL_API_KEY=mp_live_...`. |
 | `401` / `403` | Regenerate the key at magicpixel.art/settings. |
 | `whoami` shows 0 assets | The key is bound to an empty project. Mint a key for the project that has art. |
 | `index.ts` doesn't update | Run `sync --full` once; renames may take a full pass to propagate. |

package/dist/commands/doctor.js

@@ -0,0 +1,92 @@
+import kleur from 'kleur';
+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 { detectFramework, hasPackageJson } from '../util/framework.js';
+import { CLI_VERSION } from '../version.js';
+/**
+ * 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.
+ */
+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
+    const framework = await detectFramework();
+    push(`package.json:       ${hasPackageJson() ? 'found' : kleur.yellow('missing')}`);
+    push(`Framework detected: ${framework ?? kleur.dim('none')}`);
+    // Config
+    let config = 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]})`);
+    }
+    push(`API endpoint:       ${resolveEndpoint(config ?? { ...defaultConfig })}`);
+    // Key source
+    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');
+        if (existsSync(pkgPath)) {
+            const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
+            watchScript = pkg.scripts?.['magicpixel:watch'] ?? null;
+        }
+    }
+    catch {
+        // ignore
+    }
+    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)
+    if (config) {
+        const out = resolve(process.cwd(), config.outDir);
+        if (existsSync(out)) {
+            push(`outDir on disk:     ${relative(process.cwd(), out)} (exists)`);
+        }
+        else {
+            push(`outDir on disk:     ${kleur.dim('not created yet')}`);
+        }
+    }
+    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.'));
+    }
+    console.log(lines.join('\n'));
+}

package/dist/commands/init.js

@@ -5,6 +5,9 @@ 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';
+const WATCH_SCRIPT_NAME = 'magicpixel:watch';
+const WATCH_SCRIPT_CMD = 'magicpixel sync --watch';
 export async function initCommand(opts) {
     const path = configPath();
     if (existsSync(path) && !opts.force) {
@@ -17,6 +20,9 @@ export async function initCommand(opts) {
     const framework = await detectFramework();
     const suggestedOutDir = suggestOutDir(framework);
     config.outDir = suggestedOutDir;
+    const pkgExists = hasPackageJson();
+    const pkgPath = resolve(process.cwd(), 'package.json');
+    let addWatchScript = pkgExists;
     if (interactive) {
         const rl = createInterface({ input: stdin, output: stdout });
         try {
@@ -37,6 +43,10 @@ export async function initCommand(opts) {
             }
             const giAns = (await rl.question(`${kleur.cyan('?')} Add .magicpixel/ to .gitignore? ${kleur.dim('(Y/n)')} `)).trim().toLowerCase();
             addGitignore = giAns !== 'n' && giAns !== 'no';
+            if (pkgExists) {
+                const wAns = (await rl.question(`${kleur.cyan('?')} Add a "${WATCH_SCRIPT_NAME}" script to package.json? ${kleur.dim('(Y/n)')} `)).trim().toLowerCase();
+                addWatchScript = wAns !== 'n' && wAns !== 'no';
+            }
         }
         finally {
             rl.close();
@@ -53,54 +63,59 @@ export async function initCommand(opts) {
         if (added)
             console.log(kleur.green('✓ added .magicpixel/ to .gitignore'));
     }
-    console.log();
-    console.log(kleur.bold('Next:'));
-    console.log(`  1. Get an API key → ${kleur.cyan('https://magicpixel.art/settings')}`);
-    console.log(`  2. ${kleur.dim('export')} MAGICPIXEL_API_KEY=mp_live_...`);
-    console.log(`  3. ${kleur.dim('npx')} magicpixel sync`);
-    console.log();
-    console.log(kleur.dim('Tip: use `magicpixel sync --watch` while editing.'));
-}
-async function detectFramework() {
-    try {
-        const pkgPath = resolve(process.cwd(), 'package.json');
-        if (!existsSync(pkgPath))
-            return null;
-        const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
-        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
-        if (deps['next'])
-            return 'Next.js';
-        if (deps['vite'])
-            return 'Vite';
-        if (deps['@remix-run/react'])
-            return 'Remix';
-        if (deps['react-scripts'])
-            return 'Create React App';
-        if (deps['astro'])
-            return 'Astro';
-        if (deps['nuxt'])
-            return 'Nuxt';
-        if (deps['@sveltejs/kit'])
-            return 'SvelteKit';
-        return null;
+    let watchScriptAdded = false;
+    if (addWatchScript && pkgExists) {
+        const r = await ensureWatchScript(pkgPath);
+        watchScriptAdded = r.added;
+        if (r.added)
+            console.log(kleur.green(`✓ added "${WATCH_SCRIPT_NAME}" script to package.json`));
+        else if (r.alreadyPresent)
+            console.log(kleur.dim(`  "${WATCH_SCRIPT_NAME}" script already present in package.json`));
+        else if (r.error)
+            console.log(kleur.yellow(`  could not patch package.json: ${r.error}`));
     }
-    catch {
-        return null;
+    // Only print the "Next" block in fully-interactive init runs. `start`
+    // orchestrates its own onboarding summary, so doubling them up is noisy.
+    if (interactive) {
+        console.log();
+        console.log(kleur.bold('Next:'));
+        console.log(`  1. ${kleur.dim('magicpixel login')}    ${kleur.dim('# paste your key from https://magicpixel.art/settings')}`);
+        console.log(`  2. ${kleur.dim('magicpixel sync')}     ${kleur.dim('# downloads your assets')}`);
+        if (watchScriptAdded) {
+            console.log(`  3. ${kleur.dim('npm run')} ${WATCH_SCRIPT_NAME}    ${kleur.dim('# keeps assets fresh while you edit')}`);
+        }
+        else {
+            console.log(`  3. ${kleur.dim('npx')} magicpixel sync --watch    ${kleur.dim('# keeps assets fresh while you edit')}`);
+        }
+        console.log();
     }
 }
-function suggestOutDir(framework) {
-    switch (framework) {
-        case 'Next.js':
-        case 'Astro':
-        case 'Nuxt':
-        case 'Create React App':
-            return 'public/magicpixel';
-        case 'SvelteKit':
-            return 'static/magicpixel';
-        case 'Vite':
-        case 'Remix':
-        default:
-            return 'src/assets/magicpixel';
+/**
+ * Add a `magicpixel:watch` npm script. Preserves existing scripts and 2-space
+ * indentation; never overwrites a user-defined script of the same name.
+ */
+async function ensureWatchScript(pkgPath) {
+    try {
+        const raw = await readFile(pkgPath, 'utf8');
+        let pkg;
+        try {
+            pkg = JSON.parse(raw);
+        }
+        catch (e) {
+            return { added: false, alreadyPresent: false, error: `package.json is not valid JSON (${e.message})` };
+        }
+        const scripts = (pkg.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {});
+        if (typeof scripts[WATCH_SCRIPT_NAME] === 'string') {
+            return { added: false, alreadyPresent: true };
+        }
+        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');
+        return { added: true, alreadyPresent: false };
+    }
+    catch (e) {
+        return { added: false, alreadyPresent: false, error: e.message };
     }
 }
 /**

package/dist/commands/login.js

@@ -0,0 +1,98 @@
+import kleur from 'kleur';
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import { resolveEndpoint, loadConfig, defaultConfig } from '../config.js';
+import { writeCredentials, credentialsPath } from '../util/credentials.js';
+import { safeFetch } from '../util/security.js';
+import { CLI_USER_AGENT } from '../version.js';
+import { existsSync } from 'node:fs';
+import { relative } from 'node:path';
+const KEY_RE = /^mp_(live|test)_[a-f0-9]{64}$/;
+export async function loginCommand(opts = {}) {
+    // Config is optional for `login` — a brand-new user runs it before `init`.
+    let config;
+    try {
+        config = await loadConfig();
+    }
+    catch {
+        config = { ...defaultConfig };
+    }
+    let key = opts.key?.trim();
+    if (!key) {
+        if (!stdin.isTTY) {
+            throw new Error('magicpixel login: no key provided and stdin is not a TTY.\n' +
+                '  Fix: pass --key mp_live_… or run interactively.');
+        }
+        key = await promptForKey(3, config);
+    }
+    else {
+        if (!KEY_RE.test(key)) {
+            throw new Error(`That key doesn't look right (expected mp_live_… or mp_test_…).\n` +
+                `  Fix: copy a fresh key from https://magicpixel.art/settings.`);
+        }
+        await assertKeyValid(key, config);
+    }
+    const path = await writeCredentials(key);
+    console.log();
+    console.log(kleur.green('✓ logged in'));
+    console.log(kleur.dim(`  Key stored at ${relative(process.cwd(), path)} (mode 0600).`));
+    if (process.env.MAGICPIXEL_API_KEY) {
+        console.log(kleur.yellow('  Note: MAGICPIXEL_API_KEY is still set in your environment and takes precedence.'));
+    }
+}
+async function promptForKey(maxAttempts, config) {
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            const answer = (await rl.question(`${kleur.cyan('?')} Paste your key from ${kleur.cyan('https://magicpixel.art/settings')} ${kleur.dim("(we'll store it in .magicpixel/credentials, gitignored)")}: `)).trim();
+            if (!answer) {
+                console.log(kleur.yellow('  No key entered.'));
+                continue;
+            }
+            if (!KEY_RE.test(answer)) {
+                console.log(kleur.yellow(`  That doesn't look like a MagicPixel key (expected mp_live_… or mp_test_…).`));
+                continue;
+            }
+            try {
+                await assertKeyValid(answer, config);
+                return answer;
+            }
+            catch (e) {
+                console.log(kleur.yellow(`  ${e.message.split('\n')[0]}`));
+            }
+        }
+        throw new Error(`Gave up after ${maxAttempts} attempts.\n  Fix: generate a fresh key at https://magicpixel.art/settings and re-run.`);
+    }
+    finally {
+        rl.close();
+    }
+}
+async function assertKeyValid(key, config) {
+    const url = new URL(`${resolveEndpoint(config)}/manifest`);
+    url.searchParams.set('limit', '1');
+    let res;
+    try {
+        res = await safeFetch(url.href, {
+            headers: { Authorization: `Bearer ${key}`, 'User-Agent': CLI_USER_AGENT },
+        });
+    }
+    catch (e) {
+        throw new Error(`Could not reach MagicPixel (${e.message}). Try again in a moment.`);
+    }
+    if (res.status === 401 || res.status === 403) {
+        await res.body?.cancel();
+        throw new Error('Key was rejected (401). Generate a fresh one at https://magicpixel.art/settings.');
+    }
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`Server returned ${res.status}: ${body.slice(0, 120)}`);
+    }
+    await res.body?.cancel();
+}
+// Kept here so `start` can reuse the same exact prompt-and-validate flow.
+export async function promptAndStoreKey(config) {
+    if (existsSync(credentialsPath()) && !stdin.isTTY)
+        return;
+    const key = await promptForKey(3, config);
+    await writeCredentials(key);
+}

package/dist/commands/logout.js

@@ -0,0 +1,17 @@
+import kleur from 'kleur';
+import { deleteCredentials, credentialsPath } from '../util/credentials.js';
+import { relative } from 'node:path';
+export async function logoutCommand() {
+    const path = credentialsPath();
+    const removed = await deleteCredentials();
+    if (removed) {
+        console.log(kleur.green(`✓ logged out`));
+        console.log(kleur.dim(`  Removed ${relative(process.cwd(), path)}.`));
+    }
+    else {
+        console.log(kleur.dim('No stored credentials to remove.'));
+    }
+    if (process.env.MAGICPIXEL_API_KEY) {
+        console.log(kleur.yellow('  Note: MAGICPIXEL_API_KEY is still set in your environment — unset it to fully log out.'));
+    }
+}

package/dist/commands/start.js

@@ -0,0 +1,105 @@
+import kleur from 'kleur';
+import { existsSync } from 'node:fs';
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import { resolve } from 'node:path';
+import { configPath } from '../config.js';
+import { hasPackageJson } from '../util/framework.js';
+import { findKeyInDotenv, readCredentialsSync, writeCredentials } from '../util/credentials.js';
+import { initCommand } from './init.js';
+import { loginCommand } from './login.js';
+import { syncCommand } from './sync.js';
+/**
+ * One-command bootstrap for new users. Runs init → key prompt → first sync →
+ * prints copy-pasteable watch instructions. Designed so a non-technical user
+ * can paste `npx magicpixel start` and end up with sprites on disk and a watch
+ * script ready to run.
+ */
+export async function startCommand(opts = {}) {
+    console.log(kleur.bold('🪄  MagicPixel — first-run setup'));
+    console.log(kleur.dim('  This walks you through getting your sprites onto disk.'));
+    console.log();
+    // 1. Need a package.json — refuse to scaffold into a non-project directory.
+    if (!hasPackageJson()) {
+        console.log(kleur.yellow('  MagicPixel needs a JavaScript project (package.json) to sync into.\n' +
+            '  Run this inside your project folder — the one with package.json.'));
+        return;
+    }
+    // 2. Run init non-interactively unless config already exists.
+    const cfgPath = configPath();
+    if (existsSync(cfgPath) && !opts.force) {
+        console.log(kleur.dim(`  Found existing magicpixel.json — skipping init.`));
+    }
+    else {
+        await initCommand({ yes: true, force: opts.force });
+    }
+    // 3. Offer to migrate any key sitting in .env / .env.local.
+    await maybeMigrateDotenvKey();
+    // 4. Make sure we have a usable key. Env var or stored credentials are fine.
+    const haveEnv = !!process.env.MAGICPIXEL_API_KEY;
+    const stored = readCredentialsSync();
+    if (!haveEnv && !stored) {
+        console.log();
+        console.log(kleur.bold('Step: connect your account'));
+        await loginCommand();
+    }
+    else if (haveEnv) {
+        console.log(kleur.dim('  Using MAGICPIXEL_API_KEY from your environment.'));
+    }
+    else {
+        console.log(kleur.dim('  Using stored credentials from .magicpixel/credentials.'));
+    }
+    // 5. First sync.
+    console.log();
+    console.log(kleur.bold('Step: first sync'));
+    await syncCommand({ full: true });
+    // 6. Tell the user how to run the watch loop.
+    console.log();
+    console.log(kleur.bold('You\'re set up. ✨'));
+    console.log();
+    console.log(`  ${kleur.green('▶')} ${kleur.bold('npm run magicpixel:watch')}   ${kleur.dim('# keeps sprites fresh while you edit them in MagicPixel')}`);
+    console.log();
+    if (await hasDevScript()) {
+        console.log(kleur.dim('  Tip: run your dev server and the watcher together with'));
+        console.log(kleur.dim('       `npx concurrently "npm run dev" "npm run magicpixel:watch"`'));
+        console.log();
+    }
+}
+async function hasDevScript() {
+    try {
+        const path = resolve(process.cwd(), 'package.json');
+        if (!existsSync(path))
+            return false;
+        const { readFile } = await import('node:fs/promises');
+        const pkg = JSON.parse(await readFile(path, 'utf8'));
+        return typeof pkg.scripts?.dev === 'string';
+    }
+    catch {
+        return false;
+    }
+}
+async function maybeMigrateDotenvKey() {
+    if (process.env.MAGICPIXEL_API_KEY)
+        return;
+    if (readCredentialsSync())
+        return;
+    if (!stdin.isTTY)
+        return;
+    const found = await findKeyInDotenv();
+    if (!found)
+        return;
+    if (!/^mp_(live|test)_[a-f0-9]{64}$/.test(found.value))
+        return;
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+        const ans = (await rl.question(`${kleur.cyan('?')} Found MAGICPIXEL_API_KEY in ${found.file} — move it to .magicpixel/credentials so it stays out of your bundler? ${kleur.dim('(Y/n)')} `)).trim().toLowerCase();
+        if (ans === 'n' || ans === 'no')
+            return;
+        await writeCredentials(found.value);
+        console.log(kleur.green(`✓ migrated key from ${found.file} → .magicpixel/credentials`));
+        console.log(kleur.dim(`  You can now remove the MAGICPIXEL_API_KEY line from ${found.file}.`));
+    }
+    finally {
+        rl.close();
+    }
+}