@playcraft/cli 0.0.24 → 0.0.25

package/dist/commands/prefab.js

@@ -1,3 +1,4 @@
+import { inspect } from 'node:util';
 import { readFileSync, writeFileSync, readdirSync, statSync, existsSync } from 'fs';
 import { join, resolve } from 'path';
 import JSON5 from 'json5';
@@ -22,9 +23,50 @@ function detectProjectType(projectDir) {
     process.exit(1);
     throw new Error('Project type could not be detected');
 }
+const HUMAN_INSPECT = { colors: false, depth: 10, maxArrayLength: 200 };
+const JSON_OPT_DESC = '以 JSON 输出（便于脚本解析；默认为人可读文本）';
+/** 为子命令追加 `--json`（默认人类可读） */
+function withJsonOption(cmd) {
+    return cmd.option('--json', JSON_OPT_DESC);
+}
 function outputJson(data) {
     console.log(JSON.stringify(data, null, 2));
 }
+function formatHumanValue(value) {
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'undefined';
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    return inspect(value, HUMAN_INSPECT);
+}
+function outputResult(json, data, printHuman) {
+    if (json) {
+        outputJson(data);
+    }
+    else {
+        printHuman();
+    }
+}
+function projectTypeLabel(systemType) {
+    return systemType === 'external-theme' ? 'External（主题）' : 'PlayCanvas（Lite Creator）';
+}
+function describeFieldLine(f) {
+    const parts = [f.path, `类型: ${f.type}`];
+    if (f.description)
+        parts.push(f.description);
+    if (f.constraints)
+        parts.push(`(${f.constraints})`);
+    if (f.enumOptions?.length)
+        parts.push(`可选: ${f.enumOptions.join(', ')}`);
+    parts.push(`当前: ${formatHumanValue(f.currentValue)}`);
+    if (f.default !== undefined)
+        parts.push(`默认: ${formatHumanValue(f.default)}`);
+    return parts.join('  |  ');
+}
 // ─── External Theme helpers ──────────────────────────────────────────────────
 function loadThemeSchema(projectDir) {
     const raw = readLocalFile(projectDir, THEME_SCHEMA_PATH);
@@ -189,6 +231,7 @@ export function registerPrefabCommands(program) {
     const variantsHandler = (opts) => {
         const projectDir = resolveProjectDir(opts);
         const systemType = detectProjectType(projectDir);
+        const asJson = Boolean(opts.json);
         if (systemType === 'external-theme') {
             const themes = listLocalThemeIds(projectDir);
             const activeId = resolveActiveThemeId(projectDir);
@@ -197,27 +240,51 @@ export function registerPrefabCommands(program) {
                 name: id,
                 isActive: id === activeId,
             }));
-            outputJson({ projectType: 'external', variants });
+            const payload = { projectType: 'external', variants };
+            outputResult(asJson, payload, () => {
+                console.log(`项目类型: ${projectTypeLabel('external-theme')}`);
+                console.log('');
+                for (const v of variants) {
+                    const mark = v.isActive ? ' *' : '';
+                    console.log(`  ${v.id}${mark}`);
+                }
+                if (variants.some((v) => v.isActive)) {
+                    console.log('');
+                    console.log('标 * 为当前 index.ts 中的活跃主题。');
+                }
+            });
         }
         else {
             const scenes = listLocalScenes(projectDir);
-            outputJson({ projectType: 'playcanvas', variants: scenes });
+            const payload = { projectType: 'playcanvas', variants: scenes };
+            outputResult(asJson, payload, () => {
+                console.log(`项目类型: ${projectTypeLabel('lite-creator')}`);
+                console.log('');
+                if (scenes.length === 0) {
+                    console.log('（无场景）');
+                    return;
+                }
+                for (const s of scenes) {
+                    const gc = s.gameConfigPath ? `  [${s.gameConfigPath}]` : '';
+                    console.log(`  ${s.name}  (${s.id})${gc}`);
+                }
+            });
         }
     };
-    prefab.command('variants')
+    withJsonOption(prefab.command('variants'))
         .description('列出可用变体（External: 主题列表；PlayCanvas: 场景列表）')
         .option('--project-dir <path>', '项目根目录（默认 cwd）')
         .action(variantsHandler);
-    prefab.command('themes')
+    withJsonOption(prefab.command('themes'))
         .description('variants 别名（对齐前端「主题列表」术语）')
         .option('--project-dir <path>', '项目根目录（默认 cwd）')
         .action(variantsHandler);
-    prefab.command('scenes')
+    withJsonOption(prefab.command('scenes'))
         .description('variants 别名（对齐前端「场景列表」术语）')
         .option('--project-dir <path>', '项目根目录（默认 cwd）')
         .action(variantsHandler);
     // ─── list ────────────────────────────────────────────────────
-    prefab.command('list')
+    withJsonOption(prefab.command('list'))
         .description('列出所有 prefab 及状态')
         .option('--variant <id>', '指定变体（External: themeId；PlayCanvas: sceneId）')
         .option('--project-dir <path>', '项目根目录（默认 cwd）')
@@ -225,7 +292,12 @@ export function registerPrefabCommands(program) {
         const projectDir = resolveProjectDir(opts);
         const systemType = detectProjectType(projectDir);
         const prefabs = loadPrefabs(projectDir, systemType, opts);
-        outputJson({
+        const asJson = Boolean(opts.json);
+        let variantNote = opts.variant ?? null;
+        if (systemType === 'external-theme' && !opts.variant) {
+            variantNote = resolveThemeId(projectDir, opts);
+        }
+        const payload = {
             projectType: systemType === 'external-theme' ? 'external' : 'playcanvas',
             variant: opts.variant ?? null,
             total: prefabs.length,
@@ -237,10 +309,34 @@ export function registerPrefabCommands(program) {
                 isUsed: p.isUsed,
                 type: p.systemType,
             })),
+        };
+        outputResult(asJson, payload, () => {
+            console.log(`项目类型: ${projectTypeLabel(systemType)}`);
+            console.log(`变体上下文: ${variantNote ?? '（默认）'}`);
+            console.log(`共 ${prefabs.length} 个 prefab，已启用 ${prefabs.filter((p) => p.isUsed).length} 个。`);
+            console.log('');
+            const keyW = Math.min(28, Math.max(8, ...prefabs.map((p) => p.key.length)));
+            for (let i = 0; i < prefabs.length; i++) {
+                const p = prefabs[i];
+                const status = p.isUsed ? '已启用' : '未启用';
+                const label = p.key.padEnd(keyW);
+                console.log(`  ${label}  ${status}`);
+                const detailIndent = '      ';
+                if (p.name && p.name !== p.key) {
+                    console.log(`${detailIndent}名称: ${p.name}`);
+                }
+                const desc = p.description?.trim();
+                if (desc) {
+                    console.log(`${detailIndent}说明: ${desc}`);
+                }
+                if (i < prefabs.length - 1) {
+                    console.log('');
+                }
+            }
         });
     });
     // ─── describe ────────────────────────────────────────────────
-    prefab.command('describe <key>')
+    withJsonOption(prefab.command('describe <key>'))
         .description('显示 prefab 完整字段信息')
         .option('--variant <id>', '指定变体')
         .option('--project-dir <path>', '项目根目录（默认 cwd）')
@@ -253,14 +349,27 @@ export function registerPrefabCommands(program) {
             console.error(`Error: prefab "${key}" 不存在。可用的 key: ${prefabs.map((p) => p.key).join(', ')}`);
             process.exit(1);
         }
+        const asJson = Boolean(opts.json);
         if (found.systemType === 'external-theme' && found.jsonSchema) {
             const fields = describeJsonSchemaFields(found.jsonSchema, found.currentValue);
-            outputJson({
+            const payload = {
                 key: found.key,
                 type: found.systemType,
                 isUsed: found.isUsed,
                 description: found.description,
                 fields,
+            };
+            outputResult(asJson, payload, () => {
+                console.log(`Prefab: ${found.key}`);
+                console.log(`类型: ${projectTypeLabel(found.systemType)}`);
+                console.log(`状态: ${found.isUsed ? '已启用' : '未启用'}`);
+                if (found.description)
+                    console.log(`说明: ${found.description}`);
+                console.log('');
+                console.log('字段:');
+                for (const f of fields) {
+                    console.log(`  • ${describeFieldLine(f)}`);
+                }
             });
         }
         else if (found.configSchema) {
@@ -268,27 +377,51 @@ export function registerPrefabCommands(program) {
                 ? found.currentValue
                 : {};
             const fields = describeConfigSchemaFields(found.configSchema, currentValues);
-            outputJson({
+            const payload = {
                 key: found.key,
                 type: found.systemType,
                 isUsed: found.isUsed,
                 description: found.description,
                 configPath: found.configPath,
                 fields,
+            };
+            outputResult(asJson, payload, () => {
+                console.log(`Prefab: ${found.key}`);
+                console.log(`类型: ${projectTypeLabel(found.systemType)}`);
+                console.log(`状态: ${found.isUsed ? '已启用' : '未启用'}`);
+                if (found.configPath)
+                    console.log(`配置: ${found.configPath}`);
+                if (found.description)
+                    console.log(`说明: ${found.description}`);
+                console.log('');
+                console.log('字段:');
+                for (const f of fields) {
+                    console.log(`  • ${describeFieldLine(f)}`);
+                }
             });
         }
         else {
-            outputJson({
+            const payload = {
                 key: found.key,
                 type: found.systemType,
                 isUsed: found.isUsed,
                 description: found.description,
                 currentValue: found.currentValue,
+            };
+            outputResult(asJson, payload, () => {
+                console.log(`Prefab: ${found.key}`);
+                console.log(`类型: ${projectTypeLabel(found.systemType)}`);
+                console.log(`状态: ${found.isUsed ? '已启用' : '未启用'}`);
+                if (found.description)
+                    console.log(`说明: ${found.description}`);
+                console.log('');
+                console.log('当前值:');
+                console.log(formatHumanValue(found.currentValue));
             });
         }
     });
     // ─── get ─────────────────────────────────────────────────────
-    prefab.command('get <key> [field]')
+    withJsonOption(prefab.command('get <key> [field]'))
         .description('获取 prefab 或子字段的当前值')
         .option('--variant <id>', '指定变体')
         .option('--project-dir <path>', '项目根目录（默认 cwd）')
@@ -309,16 +442,27 @@ export function registerPrefabCommands(program) {
         if (field) {
             value = getByDotPath(value, field);
         }
-        outputJson({ key, field: field ?? null, value });
+        const payload = { key, field: field ?? null, value };
+        const asJson = Boolean(opts.json);
+        outputResult(asJson, payload, () => {
+            if (field) {
+                console.log(formatHumanValue(value));
+            }
+            else {
+                console.log(`${key}:`);
+                console.log(formatHumanValue(value));
+            }
+        });
     });
     // ─── set ─────────────────────────────────────────────────────
-    prefab.command('set <key> <field> <value>')
+    withJsonOption(prefab.command('set <key> <field> <value>'))
         .description('修改 prefab 子字段值（带校验）')
         .option('--variant <id>', '指定变体')
         .option('--project-dir <path>', '项目根目录（默认 cwd）')
         .action((key, field, rawValue, opts) => {
         const projectDir = resolveProjectDir(opts);
         const systemType = detectProjectType(projectDir);
+        const asJson = Boolean(opts.json);
         if (systemType === 'external-theme') {
             const themeId = resolveThemeId(projectDir, opts);
             const schema = loadThemeSchema(projectDir);
@@ -352,7 +496,10 @@ export function registerPrefabCommands(program) {
             }
             const newData = mergeThemeDataKey(data, key, newValue);
             writeThemeData(projectDir, themeId, newData);
-            outputJson({ success: true, key, field, value: coerced });
+            const payload = { success: true, key, field, value: coerced };
+            outputResult(asJson, payload, () => {
+                console.log(`已更新 ${key}.${field} = ${formatHumanValue(coerced)}`);
+            });
         }
         else {
             const configPath = resolveGameConfigPathForVariant(projectDir, opts.variant);
@@ -380,17 +527,21 @@ export function registerPrefabCommands(program) {
             const newValues = { ...currentValues, [field]: coerced };
             const updated = updateGameConfigValue(gameConfigJson, configKey, newValues);
             writeGameConfig(projectDir, configPath, updated);
-            outputJson({ success: true, key, field, value: coerced });
+            const payload = { success: true, key, field, value: coerced };
+            outputResult(asJson, payload, () => {
+                console.log(`已更新 ${key}.${field} = ${formatHumanValue(coerced)}`);
+            });
         }
     });
     // ─── enable ──────────────────────────────────────────────────
-    prefab.command('enable <key>')
+    withJsonOption(prefab.command('enable <key>'))
         .description('启用 prefab')
         .option('--variant <id>', '指定变体')
         .option('--project-dir <path>', '项目根目录（默认 cwd）')
         .action((key, opts) => {
         const projectDir = resolveProjectDir(opts);
         const systemType = detectProjectType(projectDir);
+        const asJson = Boolean(opts.json);
         if (systemType === 'external-theme') {
             const themeId = resolveThemeId(projectDir, opts);
             const schema = loadThemeSchema(projectDir);
@@ -403,39 +554,56 @@ export function registerPrefabCommands(program) {
             const defaultValue = defaultValueFromJsonSchemaProperty(props[key]);
             const newData = mergeThemeDataKey(data, key, defaultValue);
             writeThemeData(projectDir, themeId, newData);
-            outputJson({ success: true, key, enabled: true, defaultValue });
+            const payload = { success: true, key, enabled: true, defaultValue };
+            outputResult(asJson, payload, () => {
+                console.log(`已启用 prefab「${key}」，并写入 schema 默认值：`);
+                console.log(formatHumanValue(defaultValue));
+            });
         }
         else {
             const configPath = resolveGameConfigPathForVariant(projectDir, opts.variant);
             const gameConfigJson = loadGameConfig(projectDir, configPath);
             const { extensions } = parseGameConfig(gameConfigJson);
             if (extensions.includes(key)) {
-                outputJson({ success: true, key, enabled: true, message: 'Already enabled' });
+                const payload = { success: true, key, enabled: true, message: 'Already enabled' };
+                outputResult(asJson, payload, () => {
+                    console.log(`扩展「${key}」已在配置中启用，无需变更。`);
+                });
                 return;
             }
             const updated = updateGameConfigExtensions(gameConfigJson, [...extensions, key]);
             writeGameConfig(projectDir, configPath, updated);
-            outputJson({ success: true, key, enabled: true });
+            const payload = { success: true, key, enabled: true };
+            outputResult(asJson, payload, () => {
+                console.log(`已启用扩展「${key}」并更新 Game 配置。`);
+            });
         }
     });
     // ─── disable ─────────────────────────────────────────────────
-    prefab.command('disable <key>')
+    withJsonOption(prefab.command('disable <key>'))
         .description('禁用 prefab')
         .option('--variant <id>', '指定变体')
         .option('--project-dir <path>', '项目根目录（默认 cwd）')
         .action((key, opts) => {
         const projectDir = resolveProjectDir(opts);
         const systemType = detectProjectType(projectDir);
+        const asJson = Boolean(opts.json);
         if (systemType === 'external-theme') {
             const themeId = resolveThemeId(projectDir, opts);
             const data = loadThemeData(projectDir, themeId);
             if (!Object.prototype.hasOwnProperty.call(data, key)) {
-                outputJson({ success: true, key, enabled: false, message: 'Already disabled' });
+                const payload = { success: true, key, enabled: false, message: 'Already disabled' };
+                outputResult(asJson, payload, () => {
+                    console.log(`Prefab「${key}」在主题数据中本就不存在，视为已禁用。`);
+                });
                 return;
             }
             const newData = deleteThemeDataKey(data, key);
             writeThemeData(projectDir, themeId, newData);
-            outputJson({ success: true, key, enabled: false });
+            const payload = { success: true, key, enabled: false };
+            outputResult(asJson, payload, () => {
+                console.log(`已禁用 prefab「${key}」并从主题数据中移除。`);
+            });
         }
         else {
             const configPath = resolveGameConfigPathForVariant(projectDir, opts.variant);
@@ -443,21 +611,28 @@ export function registerPrefabCommands(program) {
             const { extensions } = parseGameConfig(gameConfigJson);
             const filtered = extensions.filter((n) => n !== key);
             if (filtered.length === extensions.length) {
-                outputJson({ success: true, key, enabled: false, message: 'Already disabled' });
+                const payload = { success: true, key, enabled: false, message: 'Already disabled' };
+                outputResult(asJson, payload, () => {
+                    console.log(`扩展「${key}」未在配置中启用，无需变更。`);
+                });
                 return;
             }
             const updated = updateGameConfigExtensions(gameConfigJson, filtered);
             writeGameConfig(projectDir, configPath, updated);
-            outputJson({ success: true, key, enabled: false });
+            const payload = { success: true, key, enabled: false };
+            outputResult(asJson, payload, () => {
+                console.log(`已禁用扩展「${key}」并更新 Game 配置。`);
+            });
         }
     });
     // ─── switch ──────────────────────────────────────────────────
-    prefab.command('switch <variant>')
+    withJsonOption(prefab.command('switch <variant>'))
         .description('切换活跃变体（External: 修改 index.ts；PlayCanvas: 指定场景上下文）')
         .option('--project-dir <path>', '项目根目录（默认 cwd）')
         .action((variant, opts) => {
         const projectDir = resolveProjectDir(opts);
         const systemType = detectProjectType(projectDir);
+        const asJson = Boolean(opts.json);
         if (systemType === 'external-theme') {
             const themes = listLocalThemeIds(projectDir);
             if (!themes.includes(variant)) {
@@ -466,7 +641,14 @@ export function registerPrefabCommands(program) {
             }
             const content = buildThemeIndexTs(variant);
             writeFileSync(join(projectDir, THEME_INDEX_PATH), content, 'utf-8');
-            outputJson({ success: true, activeVariant: variant, message: `Switched to theme "${variant}"` });
+            const payload = {
+                success: true,
+                activeVariant: variant,
+                message: `Switched to theme "${variant}"`,
+            };
+            outputResult(asJson, payload, () => {
+                console.log(`已切换活跃主题为「${variant}」（已写入 ${THEME_INDEX_PATH}）。`);
+            });
         }
         else {
             const scenes = listLocalScenes(projectDir);
@@ -475,10 +657,14 @@ export function registerPrefabCommands(program) {
                 console.error(`Error: 场景 "${variant}" 不存在。可用: ${scenes.map((s) => `${s.name}(${s.id})`).join(', ')}`);
                 process.exit(1);
             }
-            outputJson({
+            const payload = {
                 success: true,
                 activeVariant: found.id,
                 message: `PlayCanvas 场景上下文已设为 "${found.name}"。后续命令使用 --variant ${found.id} 来操作此场景的配置。`,
+            };
+            outputResult(asJson, payload, () => {
+                console.log(`PlayCanvas 场景上下文已设为「${found.name}」 (${found.id})。`);
+                console.log(`后续命令请使用 --variant ${found.id} 操作该场景的配置。`);
             });
         }
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.0.24",
+  "version": "0.0.25",
   "private": false,
   "type": "module",
   "bin": {
@@ -22,8 +22,8 @@
     "release": "node scripts/release.js"
   },
   "dependencies": {
-    "@playcraft/build": "^0.0.24",
-    "@playcraft/common": "^0.0.13",
+    "@playcraft/build": "^0.0.25",
+    "@playcraft/common": "^0.0.14",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
     "cors": "^2.8.6",