pixifact-cli 0.1.3 → 0.1.4

package/README.md

@@ -1,44 +1,44 @@
 # Pixifact CLI
 
-Command line tools for Pixifact Scene automation.
+Pixifact Scene 自动化命令行工具。
 
-The CLI is Bun-first in this release.
+本版本 CLI 是 Bun-first 工具。
 
-## Install
+## 安装
 
 ```bash
 bun add -d pixifact-cli
 ```
 
-## Commands
+## 命令
 
-Inspect a Scene:
+查看 Scene：
 
 ```bash
 pixifact scene inspect --project-root . --scene src/scenes/Hud.scene
 ```
 
-Validate one Scene:
+校验单个 Scene：
 
 ```bash
 pixifact scene validate --project-root . --scene src/scenes/Hud.scene
 ```
 
-Validate every compiler Scene:
+校验所有 compiler Scene：
 
 ```bash
 pixifact scene validate --project-root . --all
 ```
 
-Compile generated Scene runtime files:
+编译生成 Scene runtime 文件：
 
 ```bash
 pixifact compile-scenes --project-root .
 ```
 
-## Agent Workflow
+## Agent 工作流
 
-Codex, Claude Code, and other coding agents should edit `.scene` files directly, then run:
+Codex、Claude Code 和其他 coding agent 应直接编辑 `.scene` 文件，然后运行：
 
 ```bash
 pixifact scene validate --project-root . --all
@@ -46,9 +46,9 @@ pixifact compile-scenes --project-root .
 bun run build
 ```
 
-Do not edit generated files under `.pixifact/generated/**`.
+不要编辑 `.pixifact/generated/**` 下的生成文件。
 
-## Requirements
+## 环境要求
 
 - Bun
-- `pixifact` installed in the target project
+- 目标项目已安装 `pixifact`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pixifact-cli",
-  "version": "0.1.3",
-  "description": "CLI for Pixifact Scene automation.",
+  "version": "0.1.4",
+  "description": "Pixifact Scene 自动化 CLI。",
   "packageManager": "bun@1.3.13",
   "type": "module",
   "bin": {
@@ -12,7 +12,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/hxg2050/pixifact.git",
+    "url": "https://github.com/hxg2050/pixifact",
     "directory": "packages/pixifact-cli"
   },
   "keywords": [
@@ -31,6 +31,6 @@
     "start": "bun src/pixifact-cli.ts"
   },
   "dependencies": {
-    "pixifact": "^0.1.3"
+    "pixifact": "^0.1.4"
   }
 }

package/src/automation.ts

@@ -2,8 +2,10 @@ import fs from 'node:fs';
 import path from 'node:path';
 import {
     createSceneRevision,
+    builtinSceneAssetIds,
+    builtinSceneNameFromAssetId,
     defaultSceneSourceRoots,
-    extractSceneScriptInterface,
+    extractSceneScriptInterfaces,
     findMissingScenePartReferences,
     inspectSceneTemplate,
     isIgnoredSceneSourceDirectory,
@@ -12,32 +14,22 @@ import {
     parseSceneTemplate,
     resolveSceneReference,
     sceneLocalName,
+    toPosixPath,
     validateSceneContent,
 } from 'pixifact/compiler';
+import { readBuiltinSceneScriptSourcesSync } from 'pixifact/compiler-node';
 import {
-    container,
-    scene,
-    SceneDocument,
     parsePixifactProjectConfig,
     pixifactProjectConfigFileName,
     summarizePixifactProjectConfig,
 } from 'pixifact';
-import type { SceneSpec, NodeSpec } from 'pixifact';
-import type { SceneProjectState } from 'pixifact';
-import type { SceneTemplate, SceneTemplateInterface, SceneValidationDiagnostic } from 'pixifact/compiler';
+import type { SceneScriptInterface, SceneTemplate, SceneTemplateInterface, SceneTemplateNode, SceneValidationDiagnostic } from 'pixifact/compiler';
 
 interface ProjectFileSummary {
     path: string;
     kind: 'folder' | 'scene' | 'file';
 }
 
-interface EditableDocument {
-    projectRoot: string;
-    target: string;
-    document: SceneDocument;
-    isProjectFile: boolean;
-}
-
 interface ToolInput {
     projectRoot?: unknown;
     scenePath?: unknown;
@@ -48,34 +40,13 @@ interface ToolInput {
 type CompilerSceneValidationSuccess = ReturnType<typeof validateCompilerSceneFile> & { ok: true };
 type CompilerSceneValidationFailure = ReturnType<typeof validateCompilerSceneFile> & { ok: false };
 
-type DetailedNode = NodeSpec & {
+type DetailedCompilerNode = SceneTemplateNode & {
     locator: string;
     depth: number;
     parent?: string;
     childCount: number;
 }
 
-interface NodeSummary {
-    id?: string;
-    key?: string;
-    role?: string;
-    name?: string;
-    kind: NodeSpec['kind'];
-    locator: string;
-    depth: number;
-    transform?: NodeSpec['transform'];
-    components: Array<{
-        id?: string;
-        type: string;
-        propKeys: string[];
-    }>;
-    childCount: number;
-    children: NodeSummary[];
-}
-
-const projectStateType = 'pixifact.aiEditorProject';
-const sceneType = 'scene';
-
 function isRecord(value: unknown): value is Record<string, unknown> {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -128,58 +99,24 @@ function writeTextFile(filePath: string, value: string) {
     fs.writeFileSync(filePath, value, 'utf8');
 }
 
-function writeNewJsonFile(filePath: string, value: unknown) {
+function writeNewTextFile(filePath: string, value: string, errorMessage: string) {
     try {
-        fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, {
+        fs.writeFileSync(filePath, value, {
             encoding: 'utf8',
             flag: 'wx',
         });
     } catch (error) {
         if (isRecord(error) && error.code === 'EEXIST') {
-            throw new Error('Scene file already exists.');
+            throw new Error(errorMessage);
         }
         throw error;
     }
 }
 
-function isProjectState(value: unknown): value is SceneProjectState {
-    return isRecord(value)
-        && value.version === 1
-        && value.type === projectStateType
-        && isRecord(value.scene)
-        && (value.scene as { type?: unknown }).type === sceneType;
-}
-
-function isScene(value: unknown): value is SceneSpec {
-    return isRecord(value)
-        && value.version === 1
-        && value.type === sceneType
-        && isRecord(value.root);
-}
-
-function loadEditableDocument(projectRoot: unknown, scenePath: unknown): EditableDocument {
-    const { root, target } = resolveProjectPath(projectRoot, scenePath);
-    const content = readJsonFile(target);
-    if (isProjectState(content)) {
-        const document = new SceneDocument(content.scene);
-        document.loadState(content);
-        return {
-            projectRoot: root,
-            target,
-            document,
-            isProjectFile: true,
-        };
-    }
-    if (!isScene(content)) {
-        throw new Error('Target file must be a Pixifact Scene or AI editor project JSON.');
+function assertNewFile(filePath: string, errorMessage: string) {
+    if (fs.existsSync(filePath)) {
+        throw new Error(errorMessage);
     }
-    const document = new SceneDocument(content);
-    return {
-        projectRoot: root,
-        target,
-        document,
-        isProjectFile: false,
-    };
 }
 
 function loadCompilerScene(projectRoot: unknown, scenePath: unknown) {
@@ -217,7 +154,12 @@ function collectAssetFiles(root: string, directory: string, assets: Set<string>)
 }
 
 function collectCompilerSceneInterfaces(root: string, skippedScene?: string) {
-    const interfaces: Record<string, SceneTemplateInterface> = {};
+    const sceneSources: {
+        scenePath: string;
+        template: SceneTemplate;
+        scriptPath: string;
+        scriptSource: string;
+    }[] = [];
 
     for (const scenePath of collectCompilerScenePaths(root)) {
         if (scenePath === skippedScene) {
@@ -225,11 +167,49 @@ function collectCompilerSceneInterfaces(root: string, skippedScene?: string) {
         }
         try {
             const template = parseSceneTemplate(readTextFile(path.join(root, scenePath)));
-            const pair = readCompilerScenePairContract(root, scenePath, template);
+            const scriptPath = pairedSceneScriptPath(scenePath);
+            const absoluteScriptPath = path.join(root, scriptPath);
+            if (!fs.existsSync(absoluteScriptPath)) {
+                continue;
+            }
+            sceneSources.push({
+                scenePath,
+                template,
+                scriptPath,
+                scriptSource: readTextFile(absoluteScriptPath),
+            });
+        } catch {
+            continue;
+        }
+    }
+
+    const builtinSources = readBuiltinSceneScriptSourcesSync();
+    const descriptors = extractSceneScriptInterfaces([
+        ...builtinSceneAssetIds().map((scene) => {
+            const name = builtinSceneNameFromAssetId(scene);
+            return {
+                scene,
+                fileName: `${name}.ts`,
+                source: builtinSources[name],
+            };
+        }),
+        ...sceneSources.map((source) => ({
+            scene: source.scenePath,
+            fileName: source.scriptPath,
+            source: source.scriptSource,
+        })),
+    ]);
+    const interfaces: Record<string, SceneTemplateInterface> = Object.fromEntries(
+        builtinSceneAssetIds().map((scene) => [scene, descriptors[scene].interface]),
+    );
+
+    for (const source of sceneSources) {
+        try {
+            const pair = readCompilerScenePairContract(root, source.scenePath, source.template, descriptors[source.scenePath]);
             if (pair.diagnostics.length > 0 || !pair.sceneInterface) {
                 continue;
             }
-            interfaces[scenePath] = pair.sceneInterface;
+            interfaces[source.scenePath] = pair.sceneInterface;
         } catch {
             continue;
         }
@@ -299,6 +279,7 @@ function readCompilerScenePairContract(
     root: string,
     scenePath: string,
     template: SceneTemplate,
+    descriptor?: SceneScriptInterface,
 ): { diagnostics: SceneValidationDiagnostic[]; sceneInterface?: SceneTemplateInterface } {
     const expectedName = sceneLocalName(scenePath);
     if (template.name !== expectedName) {
@@ -315,20 +296,29 @@ function readCompilerScenePairContract(
         };
     }
 
-    let descriptor: ReturnType<typeof extractSceneScriptInterface>;
+    let sceneDescriptor = descriptor;
     try {
-        descriptor = extractSceneScriptInterface(readTextFile(absoluteScriptPath), absoluteScriptPath, { scene: scenePath });
+        sceneDescriptor ??= extractSceneScriptInterfaces([{
+            scene: scenePath,
+            fileName: absoluteScriptPath,
+            source: readTextFile(absoluteScriptPath),
+        }])[scenePath];
     } catch (error) {
         return {
             diagnostics: [compilerSceneScriptContractDiagnostic(error)],
         };
     }
-    if (descriptor.className !== template.name) {
+    if (!sceneDescriptor) {
         return {
-            diagnostics: [compilerSceneClassDiagnostic(template.name, descriptor.className)],
+            diagnostics: [compilerSceneScriptContractDiagnostic(new Error('No @scene decorator found.'))],
         };
     }
-    const missingParts = findMissingScenePartReferences(template, descriptor.parts);
+    if (sceneDescriptor.className !== template.name) {
+        return {
+            diagnostics: [compilerSceneClassDiagnostic(template.name, sceneDescriptor.className)],
+        };
+    }
+    const missingParts = findMissingScenePartReferences(template, sceneDescriptor.parts);
     if (missingParts.length > 0) {
         return {
             diagnostics: missingParts.map((part) => compilerScenePartDiagnostic(part.property, part.id)),
@@ -337,7 +327,7 @@ function readCompilerScenePairContract(
 
     return {
         diagnostics: [],
-        sceneInterface: descriptor.interface,
+        sceneInterface: sceneDescriptor.interface,
     };
 }
 
@@ -452,71 +442,6 @@ function validateAllCompilerScenes(root: string) {
     };
 }
 
-function nodeLocator(node: NodeSpec) {
-    return node.id ?? node.key ?? node.name ?? '';
-}
-
-function summarizeNode(node: NodeSpec, depth = 0): NodeSummary {
-    const children = node.kind === 'container' ? node.children ?? [] : [];
-    return {
-        id: node.id,
-        key: node.key,
-        role: node.role,
-        name: node.name,
-        kind: node.kind,
-        locator: nodeLocator(node),
-        depth,
-        transform: node.transform,
-        components: (node.components ?? []).map((component) => ({
-            id: component.id,
-            type: component.type,
-            propKeys: Object.keys(component.props ?? {}),
-        })),
-        childCount: children.length,
-        children: children.map((child) => summarizeNode(child, depth + 1)),
-    };
-}
-
-function collectNodes(node: NodeSpec, depth = 0, parent?: string): Array<{
-    id?: string;
-    key?: string;
-    role?: string;
-    name?: string;
-    kind: NodeSpec['kind'];
-    locator: string;
-    depth: number;
-    parent?: string;
-    componentCount: number;
-    childCount: number;
-}> {
-    return [
-        {
-            id: node.id,
-            key: node.key,
-            role: node.role,
-            name: node.name,
-            kind: node.kind,
-            locator: nodeLocator(node),
-            depth,
-            parent,
-            componentCount: node.components?.length ?? 0,
-            childCount: node.kind === 'container' ? node.children?.length ?? 0 : 0,
-        },
-        ...(node.kind === 'container' ? (node.children ?? []).flatMap((child) => collectNodes(child, depth + 1, nodeLocator(node))) : []),
-    ];
-}
-
-function summarizeScene(scene: SceneSpec) {
-    const nodes = collectNodes(scene.root);
-    return {
-        name: scene.name,
-        version: scene.version,
-        nodeCount: nodes.length,
-        componentCount: nodes.reduce((sum, node) => sum + node.componentCount, 0),
-        root: summarizeNode(scene.root),
-    };
-}
-
 function walkFiles(root: string, directory: string, depth: number, maxDepth: number, results: ProjectFileSummary[]) {
     if (depth > maxDepth) {
         return;
@@ -548,6 +473,69 @@ function walkFiles(root: string, directory: string, depth: number, maxDepth: num
     }
 }
 
+function compilerNodeChildren(node: SceneTemplateNode): SceneTemplateNode[] {
+    if (node.kind === 'pixi') {
+        return node.children;
+    }
+    if (node.kind === 'sceneInstance') {
+        return Object.values(node.slots).flat();
+    }
+    return [];
+}
+
+function compilerNodeSegment(index: number, node: SceneTemplateNode) {
+    if (node.kind === 'slotOutlet') {
+        return `${index}:slot:${node.name}`;
+    }
+    return `${index}:${node.id ?? node.kind}`;
+}
+
+function collectDetailedCompilerNodes(
+    nodes: readonly SceneTemplateNode[],
+    depth = 0,
+    parent?: string,
+): DetailedCompilerNode[] {
+    return nodes.flatMap((node, index) => {
+        const locator = parent ? `${parent}/${compilerNodeSegment(index, node)}` : compilerNodeSegment(index, node);
+        const children = node.kind === 'pixi'
+            ? collectDetailedCompilerNodes(node.children, depth + 1, locator)
+            : node.kind === 'sceneInstance'
+                ? Object.entries(node.slots).flatMap(([slot, slotChildren]) => (
+                    collectDetailedCompilerNodes(slotChildren, depth + 1, `${locator}/slot:${slot}`)
+                ))
+                : [];
+        return [
+            {
+                ...structuredClone(node),
+                locator,
+                depth,
+                parent,
+                childCount: compilerNodeChildren(node).length,
+            },
+            ...children,
+        ];
+    });
+}
+
+function createBlankCompilerSceneSource(sceneName: string) {
+    return [
+        `<Scene name="${sceneName}" width="960" height="540">`,
+        '</Scene>',
+        '',
+    ].join('\n');
+}
+
+function createBlankCompilerSceneScript(sceneName: string) {
+    return [
+        "import { Group } from 'pixifact/runtime';",
+        "import { scene } from 'pixifact/compiler';",
+        '',
+        '@scene()',
+        `export class ${sceneName} extends Group {}`,
+        '',
+    ].join('\n');
+}
+
 export function createPixifactAutomation() {
     return {
         getProjectSummary(input: unknown) {
@@ -565,12 +553,15 @@ export function createPixifactAutomation() {
 
         getScene(input: unknown) {
             const args = assertRecord(input, 'input') as ToolInput;
-            const editable = loadEditableDocument(args.projectRoot, args.scenePath);
+            const loaded = loadCompilerScene(args.projectRoot, args.scenePath);
+            const template = parseSceneTemplate(loaded.content);
             return {
-                scenePath: path.relative(editable.projectRoot, editable.target),
-                sourceType: editable.isProjectFile ? 'project' : 'scene',
-                scene: editable.document.scene,
-                summary: summarizeScene(editable.document.scene),
+                ok: true,
+                sourceType: 'compiler-scene',
+                scenePath: loaded.scenePath,
+                revision: createSceneRevision(loaded.content),
+                template,
+                summary: inspectSceneTemplate(template),
             };
         },
 
@@ -578,20 +569,26 @@ export function createPixifactAutomation() {
             const args = assertRecord(input, 'input') as ToolInput;
             const { root, target } = resolveProjectPath(args.projectRoot, args.scenePath);
             const sceneName = assertString(args.name, 'name');
-            const nextScene = scene(sceneName, container('Root', {
-                id: 'root',
-                key: 'root',
-                width: 320,
-                height: 180,
-                children: [],
-            }));
-
-            writeNewJsonFile(target, nextScene);
+            const scenePath = normalizeSceneAssetId(path.relative(root, target));
+            const sourceRootFailure = compilerSceneSourceRootFailure(scenePath);
+            if (sourceRootFailure) {
+                return sourceRootFailure;
+            }
+            const scriptPath = path.resolve(root, pairedSceneScriptPath(scenePath));
+            const source = createBlankCompilerSceneSource(sceneName);
+            const template = parseSceneTemplate(source);
+
+            assertNewFile(target, 'Scene file already exists.');
+            assertNewFile(scriptPath, 'Scene script already exists.');
+            writeNewTextFile(target, source, 'Scene file already exists.');
+            writeNewTextFile(scriptPath, createBlankCompilerSceneScript(sceneName), 'Scene script already exists.');
             return {
                 ok: true,
-                scenePath: path.relative(root, target),
-                scene: nextScene,
-                summary: summarizeScene(nextScene),
+                scenePath,
+                scriptPath: toPosixPath(path.relative(root, scriptPath)),
+                revision: createSceneRevision(source),
+                template,
+                summary: inspectSceneTemplate(template),
             };
         },
 
@@ -599,11 +596,16 @@ export function createPixifactAutomation() {
             const args = assertRecord(input, 'input') as ToolInput;
             const loaded = loadCompilerScene(args.projectRoot, args.scenePath);
             const template = parseSceneTemplate(loaded.content);
+            const sceneInterface = collectCompilerSceneInterfaces(loaded.root)[loaded.scenePath];
+            if (!sceneInterface) {
+                throw new Error(`Scene "${loaded.scenePath}" requires a readable paired @scene contract.`);
+            }
             return {
                 ok: true,
                 scenePath: loaded.scenePath,
                 revision: createSceneRevision(loaded.content),
                 summary: inspectSceneTemplate(template),
+                interface: sceneInterface,
             };
         },
 
@@ -621,9 +623,10 @@ export function createPixifactAutomation() {
 
         inspectNode(input: unknown) {
             const args = assertRecord(input, 'input') as ToolInput;
-            const editable = loadEditableDocument(args.projectRoot, args.scenePath);
+            const loaded = loadCompilerScene(args.projectRoot, args.scenePath);
+            const template = parseSceneTemplate(loaded.content);
             const nodeId = assertString(args.node, 'node');
-            const node = collectDetailedNodes(editable.document.scene.root).find((item) => item.locator === nodeId);
+            const node = collectDetailedCompilerNodes(template.children).find((item) => item.locator === nodeId);
             if (!node) {
                 throw new Error(`Node "${nodeId}" was not found.`);
             }
@@ -631,16 +634,3 @@ export function createPixifactAutomation() {
         },
     };
 }
-
-function collectDetailedNodes(node: NodeSpec, depth = 0, parent?: string): DetailedNode[] {
-    return [
-        {
-            ...structuredClone(node),
-            locator: nodeLocator(node),
-            depth,
-            parent,
-            childCount: node.kind === 'container' ? node.children?.length ?? 0 : 0,
-        },
-        ...(node.kind === 'container' ? (node.children ?? []).flatMap((child) => collectDetailedNodes(child, depth + 1, nodeLocator(node))) : []),
-    ];
-}

package/src/pixifact-cli.ts

@@ -220,7 +220,7 @@ async function executeFileCommand(positionals: string[], flags: Record<string, s
     }
 
     if (area === 'scene' && action === 'get') {
-        return automation.getScene({
+        return automation.inspectCompilerScene({
             projectRoot: requireFlag(flags, 'project-root'),
             scenePath: requireFlag(flags, 'scene'),
         });