@cocos/cocos-cli-types 0.0.1-alpha.19.1 → 0.0.1-alpha.21.2

package/configuration.d.ts

@@ -9,6 +9,8 @@ declare type EventEmitterMethods = Pick<EventEmitter, 'on' | 'off' | 'once' | 'e
 
 export declare function get<T>(key: string, scope?: ConfigurationScope): Promise<T>;
 
+export declare function getMetadata(): Promise<ICocosConfigurationNode[]>;
+
 /**
  * 配置基类接口
  */
@@ -51,6 +53,36 @@ export declare interface IBaseConfiguration extends EventEmitterMethods {
     save(): Promise<boolean>;
 }
 
+export declare interface ICocosConfigurationNode {
+    id: string;
+    title: string;
+    group: string;
+    order?: number;
+    properties: Record<string, ICocosConfigurationPropertySchema>;
+}
+
+/**
+ * Cocos 配置元数据定义。
+ *
+ * 基于 COCOS_CONFIG 类型（@types/cocos.config.d.ts）展开，
+ * 按 group(顶级模块) → node(二级字段) 组织。
+ *
+ * 供 Pink 配置面板渲染使用，通过 CocosHostConfiguration.getMetadata() 返回。
+ */
+export declare interface ICocosConfigurationPropertySchema {
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    default?: unknown;
+    title?: string;
+    description?: string;
+    scope: string[];
+    enum?: any[];
+    enumDescriptions?: string[];
+    minimum?: number;
+    maximum?: number;
+    step?: number;
+    order?: number;
+}
+
 /**
  * 配置的格式
  */

package/engine.d.ts

@@ -352,4 +352,6 @@ export declare interface ModuleRenderConfig {
     migrationScript?: string;
 }
 
+export declare function startEngineCompilation(force?: boolean): Promise<void>;
+
 export { };

package/index.d.ts

@@ -1,6 +1,10 @@
 /// <reference types="node" />
 
+import { ChunkInfo } from '@cocos/creator-programming-quick-pack/lib/loader';
 import { EventEmitter } from 'events';
+import { NextFunction } from 'express';
+import { Request as Request_2 } from 'express';
+import { Response as Response_2 } from 'express';
 
 /** 动画剪辑资源的 userData */
 declare interface AnimationClipAssetUserData {
@@ -100,6 +104,23 @@ declare interface AnimationImportSetting {
 /** 所有资源处理器类型的常量数组（用于 Zod enum 和 TypeScript type） */
 declare const ASSET_HANDLER_TYPES: string[];
 
+declare enum AssetActionEnum {
+    'add' = 0,
+    'change' = 1,
+    'delete' = 2,
+    'none' = 3
+}
+
+declare interface AssetChangeInfo {
+    type: AssetChangeType;
+    uuid: string;
+    filePath: string;
+    importer: string;
+    userData: object;
+}
+
+declare type AssetChangeType = AssetActionEnum;
+
 /**
  * 资源数据库启动参数
  */
@@ -435,9 +456,12 @@ export declare namespace Configuration {
         set,
         remove,
         save,
+        getMetadata,
         IConfiguration,
         ConfigurationScope,
-        IBaseConfiguration
+        IBaseConfiguration,
+        ICocosConfigurationNode,
+        ICocosConfigurationPropertySchema
     };
 }
 
@@ -524,6 +548,7 @@ export declare namespace Engine {
         getInfo,
         getConfig,
         initEngine,
+        startEngineCompilation,
         EngineInfo,
         IFlags,
         MakeRequired,
@@ -642,6 +667,32 @@ declare function getInfo(): Promise<EngineInfo>;
 
 declare function getInfo_2(): Promise<ProjectInfo>;
 
+declare function getMetadata(): Promise<ICocosConfigurationNode[]>;
+
+declare function getProgrammingFacet(): Promise<ProgrammingFacet>;
+
+/**
+ * Get the MCP registration status.
+ */
+declare function getStatus(): {
+    registered: boolean;
+    url?: string;
+};
+
+/**
+ * Get the server running status.
+ */
+declare function getStatus_2(): {
+    running: boolean;
+    url?: string;
+};
+
+/**
+ * Get the current server base URL.
+ * Returns undefined if the server is not running.
+ */
+declare function getUrl(): string | undefined;
+
 /** glTF 动画资源的 userData */
 declare interface GltfAnimationAssetUserData {
     gltfIndex: number;
@@ -965,6 +1016,36 @@ declare interface IChunkContent {
     clips: string[];
 }
 
+declare interface ICocosConfigurationNode {
+    id: string;
+    title: string;
+    group: string;
+    order?: number;
+    properties: Record<string, ICocosConfigurationPropertySchema>;
+}
+
+/**
+ * Cocos 配置元数据定义。
+ *
+ * 基于 COCOS_CONFIG 类型（@types/cocos.config.d.ts）展开，
+ * 按 group(顶级模块) → node(二级字段) 组织。
+ *
+ * 供 Pink 配置面板渲染使用，通过 CocosHostConfiguration.getMetadata() 返回。
+ */
+declare interface ICocosConfigurationPropertySchema {
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    default?: unknown;
+    title?: string;
+    description?: string;
+    scope: string[];
+    enum?: any[];
+    enumDescriptions?: string[];
+    minimum?: number;
+    maximum?: number;
+    step?: number;
+    order?: number;
+}
+
 declare interface ICollisionMatrix {
     [x: string]: number;
 }
@@ -1077,6 +1158,25 @@ declare interface IEngineModuleConfig {
     noDeprecatedFeatures?: { value: boolean, version: string };
 }
 
+declare interface IEngineOptions {
+    /**
+     * 引擎仓库根目录。
+     */
+    root: string;
+    /**
+     * 引擎编译后的根目录。
+     */
+    distRoot: string;
+    /**
+     * 引擎基础 URL。
+     */
+    baseUrl: string;
+    /**
+     * 使用的引擎功能。
+     */
+    features: string[];
+}
+
 declare interface IEngineProjectConfig extends Exclude<IEngineConfig, 'includeModules' | 'flags' | 'noDeprecatedFeatures'> {
     configs?: Record<string, IEngineModuleConfig>;
     globalConfigKey?: string;
@@ -1164,6 +1264,11 @@ declare type IFlags = Record<string, boolean | number>;
 
 declare type IFlags_2 = Record<string, boolean | number>;
 
+declare interface IGetPostConfig {
+    url: string | RegExp;
+    handler: (req: Request_2, res: Response_2, next?: NextFunction) => Promise<void>;
+}
+
 declare interface IInitEngineInfo {
     importBase: string;
     nativeBase: string;
@@ -1219,6 +1324,13 @@ declare interface ImageMeta {
     remap?: string;
 }
 
+declare interface IMiddlewareContribution {
+    get?: IGetPostConfig[];
+    post?: IGetPostConfig[];
+    staticFiles?: IStaticFileConfig[];
+    socket?: ISocketConfig;
+}
+
 declare interface IModuleConfig {
     moduleTreeDump: {
         default: IModules;
@@ -1245,6 +1357,11 @@ declare type IModules = Record<string, IModuleItem>;
  */
 declare function importAsset(source: string, target: string, options?: AssetOperationOption): Promise<IAssetInfo[]>;
 
+declare interface ImportMap {
+    imports?: Record<string, string>;
+    scopes?: Record<string, Record<string, string>>;
+}
+
 declare function init(): Promise<void>;
 
 declare function init_2(projectPath: string): Promise<void>;
@@ -1255,10 +1372,18 @@ declare function init_4(projectPath: string): Promise<void>;
 
 declare function init_5(projectPath: string): Promise<void>;
 
-declare function init_6(projectPath: string): Promise<void>;
+/**
+ * Initialize the scene module.
+ * Registers the scene middleware and initializes scene config.
+ */
+declare function init_6(): Promise<void>;
+
+declare function init_7(projectPath: string): Promise<void>;
 
 declare function initEngine(enginePath: string, projectPath: string, serverURL?: string): Promise<void>;
 
+declare function initProgrammingFacet(): Promise<ProgrammingFacet>;
+
 declare interface IPhysicsConfig {
     gravity: IVec3Like; // （0，-10， 0）
     allowSleep: boolean; // true
@@ -1369,6 +1494,11 @@ declare interface IRedirectInfo {
     uuid: string;
 }
 
+declare interface ISocketConfig {
+    connection: (socket: any) => void;
+    disconnect: (socket: any) => void;
+}
+
 declare interface ISplashBackgroundColor {
     x: number;
     y: number;
@@ -1395,6 +1525,11 @@ declare interface ISplashSetting {
     }
 }
 
+declare interface IStaticFileConfig {
+    url: string;
+    path: string;
+}
+
 declare type ISupportCreateCCType =
 | 'cc.AnimationClip'        // 动画剪辑
 | 'cc.Script'               // 脚本（TypeScript/JavaScript）
@@ -1504,6 +1639,14 @@ declare type MacroItem = {
 
 declare type MakeRequired<T, K extends keyof T> = T & Required<Pick<T, K>>;
 
+export declare namespace Mcp {
+    export {
+        register,
+        unregister,
+        getStatus
+    };
+}
+
 declare interface MeshClusterOptions {
     enable: boolean;
     coneCluster?: boolean;
@@ -1768,6 +1911,43 @@ declare interface PrefabAssetUserData {
     syncNodeName?: string;
 }
 
+declare class ProgrammingFacet {
+    private _packerDriverUpdateCount;
+    private _asyncIteration;
+    static create(engine: IEngineOptions, projectPath: string): Promise<ProgrammingFacet>;
+    get engineRoot(): string;
+    get engineDistRoot(): string;
+    get systemJsHomeDir(): string;
+    get systemJsIndexFile(): string;
+    get engineImportMapURL(): string;
+    get packImportMapURL(): string;
+    get packResolutionDetailMapURL(): string;
+    loadPackResource(url: string): Promise<{
+        type: 'json';
+        json: unknown;
+    } | {
+        type: 'chunk';
+        chunk: ChunkInfo;
+    }>;
+    getGlobalImportMap(): Promise<ImportMap & {
+        imports: NonNullable<ImportMap['imports']>;
+    }>;
+    private reload;
+    notifyPackDriverUpdated(): Promise<any>;
+    private _staticImportMap;
+    private _engineRoot;
+    private _engineDistRoot;
+    private _systemJsHomeDir;
+    private _systemJsBundleFileName;
+    private _engineStatsQuery;
+    private _quickPackLoader;
+    private constructor();
+    private _getQuickPackLoader;
+    private _initialize;
+    private _buildSystemJs;
+    private _resetQuickPackLoader;
+}
+
 export declare namespace Project {
     export {
         init_5 as init,
@@ -1977,6 +2157,36 @@ declare function queryUUID(urlOrPath: string): Promise<string | null>;
  */
 declare function refresh(dir: string): Promise<number>;
 
+/**
+ * MCP Facade Module
+ *
+ * Called by the cocos-code utility process to register MCP middleware
+ * in an already-initialized environment.
+ * Prerequisite: the Server module must be started before calling this module.
+ * This module only handles MCP-specific work: populating the toolRegistry
+ * and registering MCP routes on the running server.
+ */
+/**
+ * Register MCP middleware on the running server.
+ *
+ * Note: the Express server must already be started via the Server module.
+ * This function only:
+ * 1. Imports API modules to populate the toolRegistry (@tool decorator side-effects)
+ * 2. Creates McpMiddleware and registers routes on the server
+ *
+ * @returns MCP endpoint URL (e.g. http://localhost:9527/mcp)
+ */
+declare function register(): Promise<string>;
+
+/**
+ * Register a middleware contribution (routes, static files, sockets)
+ * on the running server.
+ *
+ * @param name   Middleware identifier
+ * @param module Middleware contribution config
+ */
+declare function register_2(name: string, module: IMiddlewareContribution): Promise<void>;
+
 /**
  * Reimport Asset // 重新导入资源
  */
@@ -2014,9 +2224,19 @@ declare function save(force?: boolean): Promise<void>;
  */
 declare function saveAsset(pathOrUrlOrUUID: string, data: string | Buffer): Promise<IAssetInfo>;
 
-export declare namespace Scripting {
+export declare namespace Scene {
     export {
         init_6 as init,
+        startupWorker
+    };
+}
+
+export declare namespace Scripting {
+    export {
+        init_7 as init,
+        initProgrammingFacet,
+        getProgrammingFacet,
+        startCompileScript,
         SharedSettings,
         IPluginScriptInfo,
         FilterPluginOptions
@@ -2037,6 +2257,16 @@ declare interface SerializedAssetFinder {
     scenes?: Array<string | null>;
 }
 
+export declare namespace Server {
+    export {
+        start_2 as start,
+        stop_2 as stop,
+        getUrl,
+        register_2 as register,
+        getStatus_2 as getStatus
+    };
+}
+
 declare function set<T>(key: string, value: T, scope?: ConfigurationScope): Promise<boolean>;
 
 declare interface SharedSettings {
@@ -2130,6 +2360,40 @@ declare interface SpriteFrameVertices {
  */
 declare function start(): Promise<void>;
 
+/**
+ * Server Facade Module
+ *
+ * Provides a simplified interface for managing the Express HTTP server.
+ * Wraps the core server service with startup guards and status tracking.
+ */
+/**
+ * Initialize and start the Express HTTP server.
+ *
+ * @param port Optional port number; auto-selected if omitted
+ * @returns The server base URL (e.g. http://localhost:9527)
+ */
+declare function start_2(port?: number): Promise<string>;
+
+/**
+ * 在独立的子进程中运行项目脚本编译
+ * 以避免阻塞主进程
+ */
+declare function startCompileScript(assetChanges?: AssetChangeInfo[]): Promise<void>;
+
+declare function startEngineCompilation(force?: boolean): Promise<void>;
+
+/**
+ * Start the scene worker process.
+ *
+ * @param projectPath Path to the project directory
+ */
+declare function startupWorker(projectPath: string): Promise<void>;
+
+/**
+ * Stop the Express HTTP server.
+ */
+declare function stop_2(): Promise<void>;
+
 /** 支持创建的资源类型常量数组（用于 Zod enum 和 TypeScript type） */
 declare const SUPPORT_CREATE_TYPES: readonly ['animation-clip', 'typescript', 'auto-atlas', 'effect', 'scene', 'prefab', 'material', 'terrain', 'physics-material', 'label-atlas', 'render-texture', 'directory', 'effect-header'];
 
@@ -2192,6 +2456,12 @@ declare interface ThumbnailInfo {
     value: string; // 具体 icon 名字或者 image 路径，image 路径支持绝对路径、 db:// 、 project:// 、和 packages:// 下的路径
 }
 
+/**
+ * Clean up MCP state.
+ * Note: does NOT stop the Express server — use the Server module for that.
+ */
+declare function unregister(): Promise<void>;
+
 /**
  * Update Asset User Data // 更新资源用户数据
  */

package/package.json

@@ -2,7 +2,7 @@
     "name": "@cocos/cocos-cli-types",
     "description": "types for cocos cli",
     "author": "cocos cli",
-    "version": "0.0.1-alpha.19.1",
+    "version": "0.0.1-alpha.21.2",
     "main": "index.d.ts",
     "types": "index.d.ts",
     "exports": {

package/scripting.d.ts

@@ -1,3 +1,24 @@
+/// <reference types="node" />
+
+import { ChunkInfo } from '@cocos/creator-programming-quick-pack/lib/loader';
+
+declare enum AssetActionEnum {
+    'add' = 0,
+    'change' = 1,
+    'delete' = 2,
+    'none' = 3
+}
+
+declare interface AssetChangeInfo {
+    type: AssetChangeType;
+    uuid: string;
+    filePath: string;
+    importer: string;
+    userData: object;
+}
+
+declare type AssetChangeType = AssetActionEnum;
+
 export declare interface FilterPluginOptions {
     loadPluginInEditor?: boolean;
     loadPluginInWeb?: boolean;
@@ -5,8 +26,36 @@ export declare interface FilterPluginOptions {
     loadPluginInMiniGame?: boolean;
 }
 
+export declare function getProgrammingFacet(): Promise<ProgrammingFacet>;
+
+declare interface IEngineOptions {
+    /**
+     * 引擎仓库根目录。
+     */
+    root: string;
+    /**
+     * 引擎编译后的根目录。
+     */
+    distRoot: string;
+    /**
+     * 引擎基础 URL。
+     */
+    baseUrl: string;
+    /**
+     * 使用的引擎功能。
+     */
+    features: string[];
+}
+
+declare interface ImportMap {
+    imports?: Record<string, string>;
+    scopes?: Record<string, Record<string, string>>;
+}
+
 export declare function init(projectPath: string): Promise<void>;
 
+export declare function initProgrammingFacet(): Promise<ProgrammingFacet>;
+
 export declare interface IPluginScriptInfo extends PluginScriptInfo {
     url: string;
 }
@@ -19,6 +68,43 @@ declare interface PluginScriptInfo {
     uuid: string;
 }
 
+declare class ProgrammingFacet {
+    private _packerDriverUpdateCount;
+    private _asyncIteration;
+    static create(engine: IEngineOptions, projectPath: string): Promise<ProgrammingFacet>;
+    get engineRoot(): string;
+    get engineDistRoot(): string;
+    get systemJsHomeDir(): string;
+    get systemJsIndexFile(): string;
+    get engineImportMapURL(): string;
+    get packImportMapURL(): string;
+    get packResolutionDetailMapURL(): string;
+    loadPackResource(url: string): Promise<{
+        type: 'json';
+        json: unknown;
+    } | {
+        type: 'chunk';
+        chunk: ChunkInfo;
+    }>;
+    getGlobalImportMap(): Promise<ImportMap & {
+        imports: NonNullable<ImportMap['imports']>;
+    }>;
+    private reload;
+    notifyPackDriverUpdated(): Promise<any>;
+    private _staticImportMap;
+    private _engineRoot;
+    private _engineDistRoot;
+    private _systemJsHomeDir;
+    private _systemJsBundleFileName;
+    private _engineStatsQuery;
+    private _quickPackLoader;
+    private constructor();
+    private _getQuickPackLoader;
+    private _initialize;
+    private _buildSystemJs;
+    private _resetQuickPackLoader;
+}
+
 export declare interface SharedSettings {
     useDefineForClassFields: boolean;
     allowDeclareFields: boolean;
@@ -35,4 +121,10 @@ export declare interface SharedSettings {
     };
 }
 
+/**
+ * 在独立的子进程中运行项目脚本编译
+ * 以避免阻塞主进程
+ */
+export declare function startCompileScript(assetChanges?: AssetChangeInfo[]): Promise<void>;
+
 export { };