@playcraft/cli 0.0.28 → 0.0.29

package/dist/commands/image.js

@@ -1,5 +1,5 @@
 import { mkdirSync, readFileSync, statSync, writeFileSync } from 'fs';
-import { basename, dirname } from 'path';
+import { basename, dirname, join } from 'path';
 import sharp from 'sharp';
 import { AgentApiClient } from '../utils/agent-api-client.js';
 /** 单文件输入上限（字节），防止误处理巨型文件导致 OOM */
@@ -228,10 +228,75 @@ function parseResizeFitOption(raw) {
     console.error('Error: --fit must be contain|cover|fill|inside|outside');
     process.exit(1);
 }
+/** 不规则子图文件名（避免路径分隔符与非法字符） */
+function safeElementFileBase(name, fallback) {
+    const s = name.replace(/[^a-zA-Z0-9._-]+/g, '_').replace(/^\.+/, '').slice(0, 120);
+    const base = (s || fallback).replace(/\.png$/i, '');
+    return base || fallback;
+}
+/**
+ * 按分析结果将精灵图裁成逐帧 PNG，并写入 split-meta.json（供 sprite-sheet 重组参考）
+ */
+async function splitSpriteSheetToDir(inputPath, outputDir, analysis) {
+    mkdirSync(outputDir, { recursive: true });
+    // 与后端 analyze-sprite-sheet 一致：按 EXIF 摆正后再按 bounds 裁剪
+    const sheetBuf = await sharp(inputPath).rotate().toBuffer();
+    const sheetMeta = await sharp(sheetBuf).metadata();
+    const iw = sheetMeta.width ?? 0;
+    const ih = sheetMeta.height ?? 0;
+    const frames = [];
+    let written = 0;
+    if (analysis.gridType === 'irregular' && analysis.elements?.length) {
+        for (let i = 0; i < analysis.elements.length; i++) {
+            const el = analysis.elements[i];
+            const fname = `${safeElementFileBase(el.name, `frame_${i}`)}.png`;
+            const outPath = join(outputDir, fname);
+            const { x, y, w, h } = el.bounds;
+            await sharp(sheetBuf).extract({ left: x, top: y, width: w, height: h }).png().toFile(outPath);
+            frames.push({ path: fname, name: el.name, x, y, w, h });
+            written++;
+        }
+    }
+    else {
+        const { rows, columns, frameWidth, frameHeight, padding } = analysis;
+        for (let r = 0; r < rows; r++) {
+            for (let c = 0; c < columns; c++) {
+                const x = c * (frameWidth + padding);
+                const y = r * (frameHeight + padding);
+                if (x + frameWidth > iw || y + frameHeight > ih)
+                    continue;
+                const fname = `frame_r${r}_c${c}.png`;
+                const outPath = join(outputDir, fname);
+                await sharp(sheetBuf)
+                    .extract({ left: x, top: y, width: frameWidth, height: frameHeight })
+                    .png()
+                    .toFile(outPath);
+                frames.push({ path: fname, row: r, col: c, x, y, w: frameWidth, h: frameHeight });
+                written++;
+            }
+        }
+    }
+    const splitMeta = {
+        source: inputPath,
+        imageSize: { w: iw, h: ih },
+        gridType: analysis.gridType,
+        rows: analysis.rows,
+        columns: analysis.columns,
+        frameWidth: analysis.frameWidth,
+        frameHeight: analysis.frameHeight,
+        padding: analysis.padding,
+        frameCount: analysis.frameCount,
+        description: analysis.description,
+        elements: analysis.elements,
+        frames,
+    };
+    writeFileSync(join(outputDir, 'split-meta.json'), JSON.stringify(splitMeta, null, 2), 'utf-8');
+    return written;
+}
 export function registerImageCommands(program) {
     const img = program
         .command('image')
-        .description('素材工具：本地图片处理（sharp）；remove-background 调用后端 API');
+        .description('素材工具：本地图片处理（sharp）；remove-background / sprite-split --auto-detect 可调用后端 API');
     // ─── resize ──────────────────────────────────────────────────
     img.command('resize')
         .description('缩放图片（按比例或指定宽高）')
@@ -563,6 +628,71 @@ export function registerImageCommands(program) {
             handleError(e);
         }
     });
+    // ─── sprite-split ──────────────────────────────────────────────
+    img.command('sprite-split')
+        .description('拆分精灵图为逐帧 PNG + split-meta.json；--auto-detect 调用后端多模态分析网格（需 token）')
+        .requiredOption('--input <path>', '精灵图路径')
+        .requiredOption('--output-dir <dir>', '输出目录（将自动创建）')
+        .option('--auto-detect', '由后端 Vision 推断行列、帧尺寸与间距')
+        .option('--hint <text>', '传给 Vision 的上下文（如：麻将牌面，等大小网格）')
+        .option('--model <id>', '覆盖 Vision 所用 Google GenAI 模型 ID（仅与 --auto-detect 一起使用）')
+        .option('--rows <n>', '行数（手动模式必填，除非使用 --auto-detect）', cliParseInt)
+        .option('--columns <n>', '列数（手动模式必填）', cliParseInt)
+        .option('--frame-width <n>', '单帧宽度（像素，手动模式必填）', cliParseInt)
+        .option('--frame-height <n>', '单帧高度（像素，手动模式必填）', cliParseInt)
+        .option('--padding <n>', '帧间距（像素，默认 0）', cliParseInt, 0)
+        .action(async (opts) => {
+        try {
+            assertInputWithinLimit(opts.input);
+            let analysis;
+            if (opts.autoDetect) {
+                const imageBase64 = readFileSync(opts.input).toString('base64');
+                const client = new AgentApiClient();
+                analysis = await client.post('/analyze-sprite-sheet', {
+                    imageBase64,
+                    hint: typeof opts.hint === 'string' ? opts.hint : undefined,
+                    model: typeof opts.model === 'string' && opts.model.trim() ? opts.model.trim() : undefined,
+                });
+            }
+            else {
+                const rows = opts.rows;
+                const columns = opts.columns;
+                const frameWidth = opts.frameWidth;
+                const frameHeight = opts.frameHeight;
+                if (rows === undefined ||
+                    columns === undefined ||
+                    frameWidth === undefined ||
+                    frameHeight === undefined) {
+                    console.error('Error: manual mode requires --rows, --columns, --frame-width, and --frame-height (or use --auto-detect)');
+                    process.exit(1);
+                }
+                if (rows < 1 || columns < 1 || frameWidth < 1 || frameHeight < 1) {
+                    console.error('Error: rows, columns, frame-width, frame-height must be positive integers');
+                    process.exit(1);
+                }
+                const padding = opts.padding ?? 0;
+                analysis = {
+                    gridType: 'regular',
+                    rows,
+                    columns,
+                    frameWidth,
+                    frameHeight,
+                    padding,
+                    frameCount: rows * columns,
+                    description: 'Manual grid (playcraft image sprite-split)',
+                };
+            }
+            const written = await splitSpriteSheetToDir(opts.input, opts.outputDir, analysis);
+            if (written === 0) {
+                console.error('Error: no frames extracted (check grid vs image size)');
+                process.exit(1);
+            }
+            console.log(`Sprite split: ${written} frame(s) → ${opts.outputDir} (split-meta.json); grid=${analysis.gridType} ${analysis.gridType === 'regular' ? `${analysis.rows}x${analysis.columns}` : `${analysis.elements?.length ?? 0} elements`}`);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
     // ─── sprite-sheet ────────────────────────────────────────────
     img.command('sprite-sheet')
         .description('将多张图合并为精灵图，并输出帧坐标 JSON（完整本地实现）')

package/dist/commands/prefab.js

@@ -2,7 +2,7 @@ import { inspect } from 'node:util';
 import { readFileSync, writeFileSync, readdirSync, statSync, existsSync } from 'fs';
 import { join, resolve } from 'path';
 import JSON5 from 'json5';
-import { THEME_SCHEMA_PATH, THEME_INDEX_PATH, THEME_DIR, DEFAULT_GAME_PATH, MANIFEST_PATH, ASSETS_JSON_PATH, LITE_CREATOR_EXTENSIONS_DIR, themeDataPath, scenePath, defaultValueFromJsonSchemaProperty, buildThemeIndexTs, parseThemeIndexImportPath, parseThemePrefabs, mergeThemeDataKey, deleteThemeDataKey, parseExtensionMetaData, parseGameConfig, buildExtensionPrefabs, updateGameConfigValue, updateGameConfigExtensions, findConfigKeyCaseInsensitive, parseConfigKey, listScenesFromManifest, resolveGameConfigPath, validateThemeValue, validateConfigValue, describeJsonSchemaFields, describeConfigSchemaFields, getPrefabFieldDescriptors, getPrefabFieldDiffs, prefabHasSchemaDiff, } from '@playcraft/common/prefab';
+import { THEME_SCHEMA_PATH, THEME_INDEX_PATH, THEME_DIR, DEFAULT_GAME_PATH, MANIFEST_PATH, ASSETS_JSON_PATH, LITE_CREATOR_EXTENSIONS_DIR, themeDataPath, scenePath, defaultValueFromJsonSchemaProperty, buildThemeIndexTs, parseThemeIndexImportPath, parseThemePrefabs, mergeThemeDataKey, deleteThemeDataKey, parseExtensionMetaData, parseGameConfig, buildExtensionPrefabs, updateGameConfigValue, updateGameConfigExtensions, findConfigKeyCaseInsensitive, parseConfigKey, listScenesFromManifest, listScenesWithGameConfig, resolveGameConfigPath, validateThemeValue, validateConfigValue, describeJsonSchemaFields, describeConfigSchemaFields, getPrefabFieldDescriptors, getPrefabFieldDiffs, prefabHasSchemaDiff, } from '@playcraft/common/prefab';
 const DEFAULT_PAGE_LIMIT = 50;
 /** 无法识别 External / PlayCanvas 项目类型（供测试在 mock process.exit 后通过 instanceof 识别）。 */
 export class ProjectDetectError extends Error {
@@ -266,22 +266,58 @@ function scanExtensionMetaData(projectDir) {
     }
     return map;
 }
+/** Write a single field's value into MetaData.json configSchema.{field}.default */
+function writeMetaDataDefault(projectDir, extensionName, field, value) {
+    const metaPath = join(projectDir, LITE_CREATOR_EXTENSIONS_DIR, extensionName, 'MetaData.json');
+    const raw = readFileSync(metaPath, 'utf-8');
+    const metaData = JSON.parse(raw);
+    const configSchema = metaData.configSchema;
+    if (!configSchema?.[field]) {
+        throw new Error(`MetaData.json for "${extensionName}" has no configSchema.${field}`);
+    }
+    configSchema[field].default = value;
+    writeFileSync(metaPath, JSON.stringify(metaData, null, 2), 'utf-8');
+}
+/** Write multiple fields' values into MetaData.json configSchema.*.default */
+function writeMetaDataDefaults(projectDir, extensionName, values) {
+    const metaPath = join(projectDir, LITE_CREATOR_EXTENSIONS_DIR, extensionName, 'MetaData.json');
+    const raw = readFileSync(metaPath, 'utf-8');
+    const metaData = JSON.parse(raw);
+    const configSchema = metaData.configSchema;
+    if (!configSchema) {
+        throw new Error(`MetaData.json for "${extensionName}" has no configSchema`);
+    }
+    for (const [field, value] of Object.entries(values)) {
+        if (configSchema[field]) {
+            configSchema[field].default = value;
+        }
+    }
+    writeFileSync(metaPath, JSON.stringify(metaData, null, 2), 'utf-8');
+}
 function resolveGameConfigPathForVariant(projectDir, variantId) {
     if (!variantId)
-        return DEFAULT_GAME_PATH;
+        return null;
     if (!fileExists(projectDir, scenePath(variantId)))
-        return DEFAULT_GAME_PATH;
+        return null;
     const sceneJson = JSON.parse(readLocalFile(projectDir, scenePath(variantId)));
     if (!fileExists(projectDir, ASSETS_JSON_PATH))
-        return DEFAULT_GAME_PATH;
+        return null;
     const assetsJson = JSON.parse(readLocalFile(projectDir, ASSETS_JSON_PATH));
-    const resolved = resolveGameConfigPath(sceneJson, assetsJson);
-    return resolved ?? DEFAULT_GAME_PATH;
+    return resolveGameConfigPath(sceneJson, assetsJson);
 }
 function listLocalScenes(projectDir) {
     if (!fileExists(projectDir, MANIFEST_PATH))
         return [];
     const manifestJson = JSON.parse(readLocalFile(projectDir, MANIFEST_PATH));
+    if (fileExists(projectDir, ASSETS_JSON_PATH)) {
+        const assetsJson = JSON.parse(readLocalFile(projectDir, ASSETS_JSON_PATH));
+        return listScenesWithGameConfig(manifestJson, (sceneId) => {
+            const sp = scenePath(sceneId);
+            if (!fileExists(projectDir, sp))
+                return null;
+            return JSON.parse(readLocalFile(projectDir, sp));
+        }, assetsJson);
+    }
     return listScenesFromManifest(manifestJson);
 }
 function loadPrefabs(projectDir, systemType, opts) {
@@ -291,11 +327,22 @@ function loadPrefabs(projectDir, systemType, opts) {
         const data = loadThemeData(projectDir, themeId);
         return parseThemePrefabs(schema, data, themeId);
     }
-    const configPath = resolveGameConfigPathForVariant(projectDir, opts.variant);
-    const gameConfigJson = loadGameConfig(projectDir, configPath);
-    const { extensions, config } = parseGameConfig(gameConfigJson);
     const metaMap = scanExtensionMetaData(projectDir);
-    return buildExtensionPrefabs(metaMap, { extensions, config }, configPath);
+    const configPath = resolveGameConfigPathForVariant(projectDir, opts.variant);
+    if (configPath) {
+        // 有场景级 GameConfig → 从中读取 extensions 和 config
+        const gameConfigJson = loadGameConfig(projectDir, configPath);
+        const { extensions, config } = parseGameConfig(gameConfigJson);
+        return buildExtensionPrefabs(metaMap, { extensions, config }, configPath);
+    }
+    // 无场景级 GameConfig → 从 DefaultGame.json 只读 Extensions 列表（不读 Config 值）
+    if (fileExists(projectDir, DEFAULT_GAME_PATH)) {
+        const defaultGameJson = loadGameConfig(projectDir, DEFAULT_GAME_PATH);
+        const { extensions } = parseGameConfig(defaultGameJson);
+        return buildExtensionPrefabs(metaMap, { extensions, config: {} }, DEFAULT_GAME_PATH);
+    }
+    // 完全无 GameConfig → 仅根据 MetaData 构建（全部标记为未启用）
+    return buildExtensionPrefabs(metaMap, { extensions: [], config: {} }, '');
 }
 // ─── dotpath helper ──────────────────────────────────────────────────────────
 function getByDotPath(obj, path) {
@@ -818,18 +865,12 @@ export function registerPrefabCommands(program) {
             });
         }
         else {
-            const configPath = resolveGameConfigPathForVariant(projectDir, opts.variant);
-            const gameConfigJson = loadGameConfig(projectDir, configPath);
-            const { config } = parseGameConfig(gameConfigJson);
             const metaMap = scanExtensionMetaData(projectDir);
             const meta = metaMap.get(key);
             if (!meta) {
                 console.error(`Error: extension "${key}" 不存在。`);
                 process.exit(1);
             }
-            const configKey = meta.configPath ? parseConfigKey(meta.configPath) : meta.name;
-            const existingKey = findConfigKeyCaseInsensitive(config, configKey);
-            const currentValues = (existingKey ? config[existingKey] : {}) ?? {};
             const fieldDef = meta.configSchema?.[field];
             const fieldType = fieldDef?.type ?? 'string';
             const coerced = coerceValue(rawValue, fieldType);
@@ -840,9 +881,22 @@ export function registerPrefabCommands(program) {
                     process.exit(1);
                 }
             }
-            const newValues = { ...currentValues, [field]: coerced };
-            const updated = updateGameConfigValue(gameConfigJson, configKey, newValues);
-            writeGameConfig(projectDir, configPath, updated);
+            const configPath = resolveGameConfigPathForVariant(projectDir, opts.variant);
+            if (configPath) {
+                // 有场景级 GameConfig → 写入 GameConfig 文件
+                const gameConfigJson = loadGameConfig(projectDir, configPath);
+                const { config } = parseGameConfig(gameConfigJson);
+                const configKey = meta.configPath ? parseConfigKey(meta.configPath) : meta.name;
+                const existingKey = findConfigKeyCaseInsensitive(config, configKey);
+                const currentValues = (existingKey ? config[existingKey] : {}) ?? {};
+                const newValues = { ...currentValues, [field]: coerced };
+                const updated = updateGameConfigValue(gameConfigJson, configKey, newValues);
+                writeGameConfig(projectDir, configPath, updated);
+            }
+            else {
+                // 无场景级 GameConfig → 写 MetaData.json 的 configSchema.{field}.default
+                writeMetaDataDefault(projectDir, key, field, coerced);
+            }
             const payload = { success: true, key, field, value: coerced };
             outputResult(asJson, payload, () => {
                 console.log(`已更新 ${key}.${field} = ${formatHumanValue(coerced)}`);
@@ -940,38 +994,67 @@ export function registerPrefabCommands(program) {
             }
             else {
                 const configPath = resolveGameConfigPathForVariant(projectDir, opts.variant);
-                let gameConfigJson = loadGameConfig(projectDir, configPath);
                 const metaMap = scanExtensionMetaData(projectDir);
-                for (const [extKey, fieldMap] of Object.entries(batch)) {
-                    if (!fieldMap || typeof fieldMap !== 'object' || Array.isArray(fieldMap)) {
-                        throw new Error(`extension "${extKey}" 的值必须是对象（字段 map）`);
-                    }
-                    const meta = metaMap.get(extKey);
-                    if (!meta) {
-                        throw new Error(`extension "${extKey}" 不存在`);
+                if (configPath) {
+                    // 有场景级 GameConfig → 写入 GameConfig 文件
+                    let gameConfigJson = loadGameConfig(projectDir, configPath);
+                    for (const [extKey, fieldMap] of Object.entries(batch)) {
+                        if (!fieldMap || typeof fieldMap !== 'object' || Array.isArray(fieldMap)) {
+                            throw new Error(`extension "${extKey}" 的值必须是对象（字段 map）`);
+                        }
+                        const meta = metaMap.get(extKey);
+                        if (!meta) {
+                            throw new Error(`extension "${extKey}" 不存在`);
+                        }
+                        const configKey = meta.configPath ? parseConfigKey(meta.configPath) : meta.name;
+                        const { config } = parseGameConfig(gameConfigJson);
+                        const existingKey = findConfigKeyCaseInsensitive(config, configKey);
+                        let currentValues = (existingKey ? config[existingKey] : {}) ?? {};
+                        currentValues = typeof currentValues === 'object' && !Array.isArray(currentValues)
+                            ? { ...currentValues }
+                            : {};
+                        for (const [field, rawVal] of Object.entries(fieldMap)) {
+                            const fieldDef = meta.configSchema?.[field];
+                            const fieldType = fieldDef?.type ?? 'string';
+                            const coerced = coerceBatchLeaf(rawVal, fieldType);
+                            if (fieldDef) {
+                                const result = validateConfigValue(fieldDef, coerced);
+                                if (!result.valid) {
+                                    throw new Error(`${extKey}.${field}: ${result.errors.join('; ')}`);
+                                }
+                            }
+                            currentValues = setByDotPath(currentValues, field, coerced);
+                        }
+                        gameConfigJson = updateGameConfigValue(gameConfigJson, configKey, currentValues);
                     }
-                    const configKey = meta.configPath ? parseConfigKey(meta.configPath) : meta.name;
-                    const { config } = parseGameConfig(gameConfigJson);
-                    const existingKey = findConfigKeyCaseInsensitive(config, configKey);
-                    let currentValues = (existingKey ? config[existingKey] : {}) ?? {};
-                    currentValues = typeof currentValues === 'object' && !Array.isArray(currentValues)
-                        ? { ...currentValues }
-                        : {};
-                    for (const [field, rawVal] of Object.entries(fieldMap)) {
-                        const fieldDef = meta.configSchema?.[field];
-                        const fieldType = fieldDef?.type ?? 'string';
-                        const coerced = coerceBatchLeaf(rawVal, fieldType);
-                        if (fieldDef) {
-                            const result = validateConfigValue(fieldDef, coerced);
-                            if (!result.valid) {
-                                throw new Error(`${extKey}.${field}: ${result.errors.join('; ')}`);
+                    writeGameConfig(projectDir, configPath, gameConfigJson);
+                }
+                else {
+                    // 无场景级 GameConfig → 逐个写 MetaData.json defaults
+                    for (const [extKey, fieldMap] of Object.entries(batch)) {
+                        if (!fieldMap || typeof fieldMap !== 'object' || Array.isArray(fieldMap)) {
+                            throw new Error(`extension "${extKey}" 的值必须是对象（字段 map）`);
+                        }
+                        const meta = metaMap.get(extKey);
+                        if (!meta) {
+                            throw new Error(`extension "${extKey}" 不存在`);
+                        }
+                        const coercedValues = {};
+                        for (const [field, rawVal] of Object.entries(fieldMap)) {
+                            const fieldDef = meta.configSchema?.[field];
+                            const fieldType = fieldDef?.type ?? 'string';
+                            const coerced = coerceBatchLeaf(rawVal, fieldType);
+                            if (fieldDef) {
+                                const result = validateConfigValue(fieldDef, coerced);
+                                if (!result.valid) {
+                                    throw new Error(`${extKey}.${field}: ${result.errors.join('; ')}`);
+                                }
                             }
+                            coercedValues[field] = coerced;
                         }
-                        currentValues = setByDotPath(currentValues, field, coerced);
+                        writeMetaDataDefaults(projectDir, extKey, coercedValues);
                     }
-                    gameConfigJson = updateGameConfigValue(gameConfigJson, configKey, currentValues);
                 }
-                writeGameConfig(projectDir, configPath, gameConfigJson);
             }
             const payload = { success: true, updatedKeys: Object.keys(batch) };
             outputResult(asJson, payload, () => {
@@ -1011,7 +1094,7 @@ export function registerPrefabCommands(program) {
             });
         }
         else {
-            const configPath = resolveGameConfigPathForVariant(projectDir, opts.variant);
+            const configPath = resolveGameConfigPathForVariant(projectDir, opts.variant) ?? DEFAULT_GAME_PATH;
             const gameConfigJson = loadGameConfig(projectDir, configPath);
             const { extensions } = parseGameConfig(gameConfigJson);
             if (extensions.includes(key)) {
@@ -1055,7 +1138,7 @@ export function registerPrefabCommands(program) {
             });
         }
         else {
-            const configPath = resolveGameConfigPathForVariant(projectDir, opts.variant);
+            const configPath = resolveGameConfigPathForVariant(projectDir, opts.variant) ?? DEFAULT_GAME_PATH;
             const gameConfigJson = loadGameConfig(projectDir, configPath);
             const { extensions } = parseGameConfig(gameConfigJson);
             const filtered = extensions.filter((n) => n !== key);

package/dist/commands/tools.js

@@ -3,6 +3,7 @@ import { dirname, join, parse } from 'path';
 import { tmpdir } from 'os';
 import { AgentApiClient } from '../utils/agent-api-client.js';
 const TMP_DIR = join(tmpdir(), 'playcraft');
+const MAX_REFERENCE_IMAGES = 8;
 function ensureTmpDir() {
     mkdirSync(TMP_DIR, { recursive: true });
 }
@@ -85,11 +86,18 @@ function sniffImageExtension(buf) {
 }
 /** Replace output extension when it does not match the chosen format extension. */
 function resolveImageOutputPath(outputPath, wantExt) {
-    const { dir, name, ext } = parse(outputPath);
-    if (ext.toLowerCase() === wantExt) {
+    try {
+        const { dir, name, ext } = parse(outputPath);
+        if (ext.toLowerCase() === wantExt) {
+            return outputPath;
+        }
+        return join(dir, `${name}${wantExt}`);
+    }
+    catch (e) {
+        const detail = e instanceof Error ? e.message : String(e);
+        console.warn(`Could not adjust output path for extension ${wantExt} (${detail}); using path as given: ${outputPath}`);
         return outputPath;
     }
-    return join(dir, `${name}${wantExt}`);
 }
 function collectReferenceImagePaths(value, previous) {
     return previous.concat([value]);
@@ -100,21 +108,37 @@ function mimeTypeForImagePath(filePath) {
         return 'image/png';
     if (ext === 'webp')
         return 'image/webp';
-    return 'image/jpeg';
+    if (ext === 'jpg' || ext === 'jpeg')
+        return 'image/jpeg';
+    if (ext === undefined || ext === '') {
+        throw new Error(`Reference image path has no file extension: ${filePath}. Use .png, .webp, .jpg, or .jpeg.`);
+    }
+    throw new Error(`Unsupported reference image extension ".${ext}" in ${filePath}. Only png, webp, jpg, and jpeg are allowed.`);
 }
-function readReferenceImagePayload(filePath) {
-    try {
-        return {
-            base64: readFileSync(filePath).toString('base64'),
-            mimeType: mimeTypeForImagePath(filePath),
-        };
+/** Load reference images for generate-image; skip unreadable paths after console.warn (same tolerance as output path resolve). */
+function collectReferenceImagePayloads(paths) {
+    if (paths.length === 0)
+        return undefined;
+    const out = [];
+    for (const p of paths) {
+        try {
+            const mimeType = mimeTypeForImagePath(p);
+            out.push({
+                base64: readFileSync(p).toString('base64'),
+                mimeType,
+            });
+        }
+        catch (e) {
+            const detail = e instanceof Error ? e.message : String(e);
+            const code = e && typeof e === 'object' && 'code' in e ? String(e.code) : '';
+            const hint = code ? ` (${code})` : '';
+            console.warn(`Skipping reference image (read failed): ${p}${hint}\n  ${detail}`);
+        }
     }
-    catch (e) {
-        const detail = e instanceof Error ? e.message : String(e);
-        const code = e && typeof e === 'object' && 'code' in e ? String(e.code) : '';
-        const hint = code ? ` (${code})` : '';
-        throw new Error(`Failed to read reference image: ${filePath}${hint}\n  ${detail}`);
+    if (paths.length > 0 && out.length === 0) {
+        console.warn('All reference images failed to load; continuing with text-only generation.');
     }
+    return out.length > 0 ? out : undefined;
 }
 export function registerToolsCommands(program) {
     const tools = program
@@ -131,7 +155,10 @@ export function registerToolsCommands(program) {
         .action(async (opts) => {
         try {
             const paths = opts.referenceImage ?? [];
-            const referenceImages = paths.length > 0 ? paths.map((p) => readReferenceImagePayload(p)) : undefined;
+            if (paths.length > MAX_REFERENCE_IMAGES) {
+                throw new Error(`Too many reference images: ${paths.length} paths given; maximum is ${MAX_REFERENCE_IMAGES}.`);
+            }
+            const referenceImages = collectReferenceImagePayloads(paths);
             const client = new AgentApiClient();
             const result = await client.post('/generate-image', {
                 prompt: opts.prompt,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.0.28",
+  "version": "0.0.29",
   "private": false,
   "type": "module",
   "bin": {
@@ -17,13 +17,14 @@
     "build": "tsc",
     "start": "node dist/index.js",
     "test": "vitest run",
+    "verify-sprite-overlay": "node scripts/verify-sprite-overlay.mjs",
     "link": "node scripts/bump-local.js && pnpm build && npm link",
     "unlink": "npm unlink -g @playcraft/cli",
     "release": "node scripts/release.js"
   },
   "dependencies": {
-    "@playcraft/build": "^0.0.28",
-    "@playcraft/common": "^0.0.17",
+    "@playcraft/build": "^0.0.29",
+    "@playcraft/common": "^0.0.18",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
     "cors": "^2.8.6",