@magicpixelart/cli 0.1.1 → 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 `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.
@@ -76,9 +117,13 @@ Sync is built to be cheap: a no-op run is one small manifest request, zero PNG b
 | `include`  | `string[]` | `["**/*"]`              | Globs (picomatch) matched against `folder/slug`. |
 | `exclude`  | `string[]` | `[]`                    | Globs to exclude.                                |
 | `emitIndex`| `boolean`  | `true`                  | Emit `<outDir>/index.ts` with typed asset map.   |
-| `endpoint` | `string?`  | production URL          | Override the API base (testing only).            |
+| `endpoint` | `string?`  | production URL          | Override the API base (testing only). Must be **HTTPS**. |
+
+State (`.magicpixel/state.json`) tracks `lastSync` (file mode `0600`). Add `.magicpixel/` to `.gitignore` (init offers to do this).
+
+### Custom endpoint (advanced)
 
-State (`.magicpixel/state.json`) tracks `lastSync`. Add `.magicpixel/` to `.gitignore` (init offers to do this).
+For local integration testing against `http://localhost`, set `MAGICPIXEL_ALLOW_INSECURE_ENDPOINT=1` in the environment. Do not commit custom endpoints to shared repos — `sync` warns when `endpoint` is set.
 
 ## CI usage
 
@@ -95,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
@@ -119,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/api.js

@@ -1,4 +1,5 @@
 import { resolveEndpoint, getApiKey, CLI_USER_AGENT } from './config.js';
+import { etagForSha256, MAX_ASSET_BYTES, readBodyWithLimit, safeFetch, } from './util/security.js';
 export class ApiError extends Error {
     status;
     constructor(status, message) {
@@ -43,7 +44,7 @@ export async function fetchManifestPage(opts) {
         url.searchParams.set('limit', String(opts.limit));
     let res;
     try {
-        res = await fetch(url, { headers: authHeaders() });
+        res = await safeFetch(url.href, { headers: authHeaders() });
     }
     catch (e) {
         throw new Error(`manifest: network error (${e.message}).\n` +
@@ -79,21 +80,27 @@ export async function fetchAssetBytes(config, key, knownSha) {
     url.searchParams.set('key', key);
     const headers = authHeaders();
     if (knownSha)
-        headers['If-None-Match'] = `"${knownSha}"`;
+        headers['If-None-Match'] = etagForSha256(knownSha);
     const maxAttempts = 3;
     let lastErr = null;
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
         try {
-            const res = await fetch(url, { headers });
-            if (res.status === 304)
+            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 new Uint8Array(await res.arrayBuffer());
+                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) {
-                lastErr = new ApiError(res.status, friendly(res.status, await res.text(), `download ${key}`));
+                lastErr = new ApiError(res.status, friendly(res.status, bodyText, `download ${key}`));
             }
             else {
-                throw new ApiError(res.status, friendly(res.status, await res.text(), `download ${key}`));
+                throw new ApiError(res.status, friendly(res.status, bodyText, `download ${key}`));
             }
         }
         catch (e) {

package/dist/commands/add.js

@@ -1,12 +1,14 @@
 import kleur from 'kleur';
 import { loadConfig, saveConfig } from '../config.js';
+import { assertSafeGlob } from '../util/security.js';
 export async function addCommand(glob) {
+    const pattern = assertSafeGlob(glob);
     const config = await loadConfig();
-    if (config.include.includes(glob)) {
-        console.log(kleur.yellow(`already included: ${glob}`));
+    if (config.include.includes(pattern)) {
+        console.log(kleur.yellow(`already included: ${pattern}`));
         return;
     }
-    config.include.push(glob);
+    config.include.push(pattern);
     await saveConfig(config);
-    console.log(kleur.green(`✓ added include pattern: ${glob}`));
+    console.log(kleur.green(`✓ added include pattern: ${pattern}`));
 }

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/remove.js

@@ -1,13 +1,15 @@
 import kleur from 'kleur';
 import { loadConfig, saveConfig } from '../config.js';
+import { assertSafeGlob } from '../util/security.js';
 export async function removeCommand(glob) {
+    const pattern = assertSafeGlob(glob);
     const config = await loadConfig();
     const before = config.include.length;
-    config.include = config.include.filter((g) => g !== glob);
+    config.include = config.include.filter((g) => g !== pattern);
     if (config.include.length === before) {
-        console.log(kleur.yellow(`not found in include: ${glob}`));
+        console.log(kleur.yellow(`not found in include: ${pattern}`));
         return;
     }
     await saveConfig(config);
-    console.log(kleur.green(`✓ removed include pattern: ${glob}`));
+    console.log(kleur.green(`✓ removed include pattern: ${pattern}`));
 }