@magicpixelart/cli 0.1.2 → 0.3.0

package/dist/util/credentials.js

@@ -0,0 +1,82 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { mkdir, readFile, writeFile, unlink, chmod } from 'node:fs/promises';
+import { resolve, dirname } from 'node:path';
+const CREDENTIALS_DIR = '.magicpixel';
+const CREDENTIALS_FILE = 'credentials';
+export function credentialsPath(cwd = process.cwd()) {
+    return resolve(cwd, CREDENTIALS_DIR, CREDENTIALS_FILE);
+}
+/** Synchronous read — called from `getApiKey()` which must stay sync. */
+export function readCredentialsSync(cwd = process.cwd()) {
+    const path = credentialsPath(cwd);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.apiKey === 'string' && parsed.apiKey.trim()) {
+            return { apiKey: parsed.apiKey.trim(), savedAt: typeof parsed.savedAt === 'string' ? parsed.savedAt : '' };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+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)
+    }
+    return path;
+}
+export async function deleteCredentials(cwd = process.cwd()) {
+    const path = credentialsPath(cwd);
+    if (!existsSync(path))
+        return false;
+    try {
+        await unlink(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Look for `MAGICPIXEL_API_KEY=…` in a `.env` / `.env.local` file. Returns the
+ * raw value (no validation) or `null`. Used by `init`/`start` to offer migration
+ * away from bundler-visible env files.
+ */
+export async function findKeyInDotenv(cwd = process.cwd()) {
+    for (const name of ['.env.local', '.env']) {
+        const path = resolve(cwd, name);
+        if (!existsSync(path))
+            continue;
+        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*$/);
+                if (m && m[1])
+                    return { file: name, value: m[1].trim() };
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    return null;
+}
+export function describeKeySource(cwd = process.cwd()) {
+    if (process.env.MAGICPIXEL_API_KEY)
+        return 'env';
+    if (readCredentialsSync(cwd))
+        return 'credentials-file';
+    return 'none';
+}

package/dist/util/emitIndex.js

@@ -1,40 +1,95 @@
-import { readFile, writeFile } from 'node:fs/promises';
+import { readFile, readdir, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { assertSafeAssetSegments } from './security.js';
+import { assertPathInsideRoot, assertSafeAssetSegments } from './security.js';
+const AGENT_HEADER = [
+    '// 👋 AI agents: import sprites by key, e.g.',
+    '//   import { MagicPixelAssets } from "<this-dir>";',
+    '//   const tree = MagicPixelAssets["items/tree"];',
+    '// Keys survive folder reorganization when you use MagicPixelAssetsById instead:',
+    '//   import { MagicPixelAssetsById } from "<this-dir>";',
+    '//   const tree = MagicPixelAssetsById["<asset-uuid>"];',
+].join('\n');
 /**
- * Emit `<outDir>/index.ts` with a typed map of every asset key → URL.
+ * Walk `<outDir>` and return one entry per `*.png` on disk, ordered by key.
  *
- *   import { MagicPixelAssets } from '@/assets/magicpixel';
- *   const url = MagicPixelAssets['player/walk'];
+ * The CLI used to emit the typed index straight from a manifest response. That
+ * coupled `index.ts` correctness to a successful network round-trip; a flaky
+ * manifest call left the barrel stale while the PNGs on disk were fresh. We
+ * now derive the index purely from the filesystem so it can never disagree
+ * with what bundlers will see.
+ */
+export async function scanDiskAssets(outDir, cwd = process.cwd()) {
+    const root = resolve(cwd, outDir);
+    if (!existsSync(root))
+        return [];
+    const out = [];
+    async function walk(dir, folderParts) {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const ent of entries) {
+            if (ent.isSymbolicLink())
+                continue;
+            const full = resolve(dir, ent.name);
+            try {
+                assertPathInsideRoot(full, root, 'outDir');
+            }
+            catch {
+                continue;
+            }
+            if (ent.isDirectory()) {
+                // Skip the id sidecar dir or any dotted folders — never user assets.
+                if (ent.name.startsWith('.'))
+                    continue;
+                await walk(full, [...folderParts, ent.name]);
+            }
+            else if (ent.isFile() && ent.name.toLowerCase().endsWith('.png')) {
+                const slug = ent.name.slice(0, -4);
+                const folder = folderParts.length ? folderParts.join('/') : null;
+                const key = folder ? `${folder}/${slug}` : slug;
+                out.push({ key, folder, slug });
+            }
+        }
+    }
+    await walk(root, []);
+    out.sort((a, b) => a.key.localeCompare(b.key));
+    return out;
+}
+/**
+ * Emit `<outDir>/index.ts` with a typed map of every asset key → URL, plus an
+ * id-keyed map for rename-resilient imports.
+ *
+ *   import { MagicPixelAssets, MagicPixelAssetsById } from '@/assets/magicpixel';
+ *   const a = MagicPixelAssets['player/walk'];      // breaks on rename
+ *   const b = MagicPixelAssetsById['abc123…'];      // survives rename
  *
  * Vite, webpack, esbuild, Parcel, Rollup, etc. all hash these URLs at build
  * time. No runtime, no bundler config.
  */
-export async function emitTypedIndex(outDir, manifest, cwd = process.cwd()) {
-    // Dedupe by key. A well-behaved manifest never has duplicates, but a server
-    // bug here would otherwise emit duplicate object keys and break TS compile.
+export async function emitTypedIndex(outDir, entries, cwd = process.cwd()) {
+    // Dedupe by key. The disk scan can't actually produce duplicates, but guard
+    // anyway so a future caller passing manifest entries can't break TS compile.
     const seen = new Set();
-    const sorted = [...manifest]
+    const sorted = [...entries]
         .sort((a, b) => a.key.localeCompare(b.key))
         .filter((e) => {
-        if (seen.has(e.key)) {
-            console.warn(`magicpixel: duplicate manifest key "${e.key}" — keeping first.`);
+        if (seen.has(e.key))
             return false;
-        }
         seen.add(e.key);
         return true;
     });
     const lines = [
         '// AUTOGENERATED by @magicpixelart/cli. Do not edit.',
         '// Re-runs of `magicpixel sync` overwrite this file.',
+        '//',
+        AGENT_HEADER,
         '',
     ];
-    // Use positional identifiers (asset_0, asset_1, …) so keys that differ only
-    // by non-alphanumeric chars (e.g. `player/walk` vs `player_walk`) can't
-    // collide on the JS identifier and break the consumer's TS build.
+    // Positional identifiers (asset_0, asset_1, …) avoid collisions between
+    // keys that differ only by non-alphanumeric chars (e.g. `a/b` vs `a_b`).
+    const indexByKey = new Map();
     sorted.forEach((e, i) => {
         assertSafeAssetSegments(e.folder, e.slug, e.key);
+        indexByKey.set(e.key, i);
         const rel = e.folder ? `./${e.folder}/${e.slug}.png` : `./${e.slug}.png`;
         lines.push(`import asset_${i} from ${JSON.stringify(rel)};`);
     });
@@ -47,6 +102,22 @@ export async function emitTypedIndex(outDir, manifest, cwd = process.cwd()) {
     lines.push('');
     lines.push('export type MagicPixelAssetKey = keyof typeof MagicPixelAssets;');
     lines.push('');
+    // Rename-resilient id map. Only populated for entries whose id we know
+    // (from the sidecar written by `sync`). Entries without an id are omitted
+    // rather than getting a synthetic key that could later collide.
+    lines.push('export const MagicPixelAssetsById = {');
+    for (const e of sorted) {
+        if (typeof e.id !== 'string' || e.id.length === 0)
+            continue;
+        const i = indexByKey.get(e.key);
+        if (i === undefined)
+            continue;
+        lines.push(`  ${JSON.stringify(e.id)}: asset_${i},`);
+    }
+    lines.push('} as const;');
+    lines.push('');
+    lines.push('export type MagicPixelAssetId = keyof typeof MagicPixelAssetsById;');
+    lines.push('');
     const path = resolve(cwd, outDir, 'index.ts');
     const next = lines.join('\n');
     // Skip the write when contents are identical. Avoids triggering Vite/webpack
@@ -64,3 +135,58 @@ export async function emitTypedIndex(outDir, manifest, cwd = process.cwd()) {
     await writeFile(path, next, 'utf8');
     return path;
 }
+/**
+ * Ensure an `AGENTS.md` at the repo root nudges AI tools (Lovable, Cursor,
+ * Claude Code, …) toward the typed index. Idempotent:
+ *
+ *   - If no `AGENTS.md` exists, write a short standalone one.
+ *   - If one exists without our marker, append a single fenced section.
+ *   - If our marker is already present, do nothing.
+ */
+export async function ensureAgentsDoc(outDir, cwd = process.cwd()) {
+    const path = resolve(cwd, 'AGENTS.md');
+    const importPath = guessImportPath(outDir);
+    const section = renderAgentsSection(importPath);
+    const marker = '<!-- magicpixel:start -->';
+    if (!existsSync(path)) {
+        await writeFile(path, `# AGENTS\n\n${section}\n`, 'utf8');
+        return 'created';
+    }
+    const current = await readFile(path, 'utf8');
+    if (current.includes(marker))
+        return 'unchanged';
+    const sep = current.endsWith('\n') ? '\n' : '\n\n';
+    await writeFile(path, current + sep + section + '\n', 'utf8');
+    return 'appended';
+}
+function renderAgentsSection(importPath) {
+    return [
+        '<!-- magicpixel:start -->',
+        '## MagicPixel sprites',
+        '',
+        'Pixel-art assets are synced to disk by `@magicpixelart/cli`. They are plain PNGs you can `import`.',
+        '',
+        '```ts',
+        `// 1) Import by key (matches the folder/slug shown in the MagicPixel editor):`,
+        `import { MagicPixelAssets } from "${importPath}";`,
+        `<img src={MagicPixelAssets["items/tree"]} />`,
+        '',
+        '// 2) Import by id (survives renames — pin imports that move around):',
+        `import { MagicPixelAssetsById } from "${importPath}";`,
+        `<img src={MagicPixelAssetsById["<asset-uuid>"]} />`,
+        '```',
+        '',
+        'When you rename or move an asset, `magicpixel sync` prints both the old → new key',
+        'and the matching `MagicPixelAssetsById[...]` hint so you can pick whichever you prefer.',
+        '',
+        'Keep the watcher running while you edit: `npm run magicpixel:watch`.',
+        '<!-- magicpixel:end -->',
+    ].join('\n');
+}
+function guessImportPath(outDir) {
+    const norm = outDir.replace(/\\/g, '/').replace(/^\.\//, '');
+    // `src/...` is conventionally aliased to `@/...` in Vite/Next/etc.
+    if (norm.startsWith('src/'))
+        return `@/${norm.slice(4)}`;
+    return `./${norm}`;
+}

package/dist/util/framework.js

@@ -0,0 +1,56 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+/** Read `package.json` and infer the framework from its dependencies. */
+export async function detectFramework(cwd = process.cwd()) {
+    try {
+        const pkgPath = resolve(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['@tanstack/start'])
+            return 'TanStack Start';
+        if (deps['@remix-run/react'])
+            return 'Remix';
+        if (deps['vite'])
+            return 'Vite';
+        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;
+    }
+    catch {
+        return null;
+    }
+}
+/** Default `outDir` for a detected framework. */
+export function suggestOutDir(framework, cwd = process.cwd()) {
+    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':
+        case 'TanStack Start':
+            return 'src/assets/magicpixel';
+        default:
+            // No framework detected — prefer src/ if present so the typed index is
+            // importable; otherwise fall back to a top-level assets/ dir.
+            return existsSync(resolve(cwd, 'src')) ? 'src/assets/magicpixel' : 'assets/magicpixel';
+    }
+}
+export function hasPackageJson(cwd = process.cwd()) {
+    return existsSync(resolve(cwd, 'package.json'));
+}

package/dist/util/paths.js

@@ -6,10 +6,24 @@ import { assertPathInsideRoot, assertSafeAssetSegments } from './security.js';
  * `outDir/<slug>.png`.
  */
 export function assetDiskPath(outDir, entry, cwd = process.cwd()) {
-    assertSafeAssetSegments(entry.folder, entry.slug, entry.key);
+    return resolveAssetDiskPath(outDir, entry.folder, entry.slug, entry.key, cwd);
+}
+/**
+ * Same as `assetDiskPath` but takes a raw manifest key (`folder/slug` or
+ * `slug`) — useful when we only have the prior key from a snapshot and don't
+ * want to synthesize a fake `ManifestEntry` just to reuse the safety checks.
+ */
+export function assetDiskPathFromKey(outDir, key, cwd = process.cwd()) {
+    const parts = key.split('/');
+    const slug = parts.pop() ?? key;
+    const folder = parts.length ? parts.join('/') : null;
+    return resolveAssetDiskPath(outDir, folder, slug, key, cwd);
+}
+function resolveAssetDiskPath(outDir, folder, slug, key, cwd) {
+    assertSafeAssetSegments(folder, slug, key);
     const base = resolve(cwd, outDir);
-    const file = `${entry.slug}.png`;
-    const diskPath = entry.folder ? resolve(base, entry.folder, file) : resolve(base, file);
+    const file = `${slug}.png`;
+    const diskPath = folder ? resolve(base, folder, file) : resolve(base, file);
     assertPathInsideRoot(diskPath, base, 'outDir');
     return diskPath;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magicpixelart/cli",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Sync MagicPixel pixel-art assets to your local project.",
   "type": "module",
   "bin": {