pixifact-cli 0.2.0 → 0.2.2

package/README.md

@@ -10,39 +10,34 @@ Pixifact Scene 自动化命令行工具。
 bun add -d pixifact-cli
 ```
 
-## 命令
+## AI 主路径
 
-查看 Scene：
+AI 修改 `.scene` 时优先只记这条路径：
 
 ```bash
-pixifact scene inspect --project-root . --scene src/scenes/Hud.scene
+pixifact summary
+pixifact scene inspect --scene src/scenes/Hud.scene
+pixifact scene validate --scene src/scenes/Hud.scene
+pixifact compile-scenes
 ```
 
-校验单个 Scene：
+如果多个 Scene 可能变化，把单文件校验换成：
 
 ```bash
-pixifact scene validate --project-root . --scene src/scenes/Hud.scene
+pixifact scene validate --all
 ```
 
-校验所有 compiler Scene：
+默认使用当前工作目录作为项目根目录；不在项目根目录运行时再加 `--project-root <path>`。
 
-```bash
-pixifact scene validate --project-root . --all
-```
-
-编译生成 Scene runtime 文件：
-
-```bash
-pixifact compile-scenes --project-root .
-```
+其他命令是辅助入口：`scene create` 用于新建 Scene，`node inspect` 用于已知 locator 的节点详情，`live ...` 只在 Editor 运行时读取上下文。不要使用 `scene get`，file mode 只保留 `scene inspect`。
 
 ## Agent 工作流
 
 Codex、Claude Code 和其他 coding agent 应直接编辑 `.scene` 文件，然后运行：
 
 ```bash
-pixifact scene validate --project-root . --all
-pixifact compile-scenes --project-root .
+pixifact scene validate --all
+pixifact compile-scenes
 bun run build
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixifact-cli",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Pixifact Scene 自动化 CLI。",
   "packageManager": "bun@1.3.13",
   "type": "module",
@@ -31,6 +31,6 @@
     "start": "bun src/pixifact-cli.ts"
   },
   "dependencies": {
-    "pixifact": "^0.2.0"
+    "pixifact": "^0.2.2"
   }
 }

package/src/pixifact-cli.ts

@@ -67,6 +67,14 @@ function requireFlag(flags: Record<string, string | true>, name: string) {
     return value;
 }
 
+function projectRootFlag(flags: Record<string, string | true>) {
+    const value = flags['project-root'];
+    if (value === undefined) {
+        return process.cwd();
+    }
+    return requireFlag(flags, 'project-root');
+}
+
 function jsonLine(value: unknown) {
     return `${JSON.stringify(value, null, 2)}\n`;
 }
@@ -199,9 +207,9 @@ function sourcePositionFromMessage(source: string, message: string) {
 
 async function executeFileCommand(positionals: string[], flags: Record<string, string | true>, automation: Automation) {
     const [area, action] = positionals;
+    const projectRoot = projectRootFlag(flags);
 
     if (area === 'compile-scenes' && action === undefined) {
-        const projectRoot = typeof flags['project-root'] === 'string' ? flags['project-root'] : process.cwd();
         try {
             await compileScenes({ projectRoot });
         } catch (error) {
@@ -215,20 +223,13 @@ async function executeFileCommand(positionals: string[], flags: Record<string, s
 
     if (area === 'summary' && action === undefined) {
         return automation.getProjectSummary({
-            projectRoot: requireFlag(flags, 'project-root'),
-        });
-    }
-
-    if (area === 'scene' && action === 'get') {
-        return automation.inspectCompilerScene({
-            projectRoot: requireFlag(flags, 'project-root'),
-            scenePath: requireFlag(flags, 'scene'),
+            projectRoot,
         });
     }
 
     if (area === 'scene' && action === 'create') {
         return automation.createScene({
-            projectRoot: requireFlag(flags, 'project-root'),
+            projectRoot,
             scenePath: requireFlag(flags, 'scene'),
             name: requireFlag(flags, 'name'),
         });
@@ -236,7 +237,7 @@ async function executeFileCommand(positionals: string[], flags: Record<string, s
 
     if (area === 'scene' && action === 'inspect') {
         return automation.inspectCompilerScene({
-            projectRoot: requireFlag(flags, 'project-root'),
+            projectRoot,
             scenePath: requireFlag(flags, 'scene'),
         });
     }
@@ -247,18 +248,18 @@ async function executeFileCommand(positionals: string[], flags: Record<string, s
                 throw new Error('Use either --all or --scene, not both.');
             }
             return automation.validateAllCompilerScenes({
-                projectRoot: requireFlag(flags, 'project-root'),
+                projectRoot,
             });
         }
         return automation.validateCompilerScene({
-            projectRoot: requireFlag(flags, 'project-root'),
+            projectRoot,
             scenePath: requireFlag(flags, 'scene'),
         });
     }
 
     if (area === 'node' && action === 'inspect') {
         return automation.inspectNode({
-            projectRoot: requireFlag(flags, 'project-root'),
+            projectRoot,
             scenePath: requireFlag(flags, 'scene'),
             node: requireFlag(flags, 'node'),
         });
@@ -299,19 +300,27 @@ export async function executePixifactCli(argv: string[], options: CliOptions = {
             return {
                 exitCode: 0,
                 stdout: jsonLine({
-                    commands: [
-                        'compile-scenes',
+                    aiPrimaryCommands: [
                         'summary',
-                        'scene create',
-                        'scene get',
-                        'scene inspect',
-                        'scene validate',
+                        'scene inspect --scene <scene-path>',
+                        'scene validate --scene <scene-path>',
+                        'compile-scenes',
+                    ],
+                    aiValidationAlternatives: [
                         'scene validate --all',
-                        'node inspect',
+                    ],
+                    auxiliaryCommands: [
+                        'scene create --scene <scene-path> --name <SceneName>',
+                        'node inspect --scene <scene-path> --node <locator>',
+                    ],
+                    liveContextCommands: [
                         'live summary',
                         'live scene get',
-                        'live node inspect',
+                        'live node inspect --node <locator>',
                     ],
+                    defaults: {
+                        projectRoot: 'current working directory',
+                    },
                 }),
                 stderr: '',
             };