@iwsdk/cli 0.4.2 → 0.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +21 -1
- package/dist/agent-adapters.d.ts +37 -0
- package/dist/agent-adapters.d.ts.map +1 -0
- package/dist/argv.d.ts +1 -0
- package/dist/argv.d.ts.map +1 -1
- package/dist/cli.js +3883 -658
- package/dist/cli.js.map +1 -1
- package/dist/commands/adapter.d.ts +3 -0
- package/dist/commands/adapter.d.ts.map +1 -1
- package/dist/commands/dev.d.ts +27 -0
- package/dist/commands/dev.d.ts.map +1 -1
- package/dist/commands/runtime.d.ts.map +1 -1
- package/dist/contract.js +1741 -113
- package/dist/contract.js.map +1 -1
- package/dist/help.d.ts +2 -0
- package/dist/help.d.ts.map +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3883 -658
- package/dist/index.js.map +1 -1
- package/dist/mcp-adapters.d.ts +2 -0
- package/dist/mcp-adapters.d.ts.map +1 -1
- package/dist/mcp-stdio.d.ts.map +1 -1
- package/dist/{hzdb-telemetry.d.ts → metavr-telemetry.d.ts} +1 -1
- package/dist/metavr-telemetry.d.ts.map +1 -0
- package/dist/runtime-contract.d.ts +30 -3
- package/dist/runtime-contract.d.ts.map +1 -1
- package/dist/runtime-state.d.ts.map +1 -1
- package/dist/runtime-transport.d.ts +6 -2
- package/dist/runtime-transport.d.ts.map +1 -1
- package/guidance/AGENTS.md +151 -0
- package/package.json +6 -5
- package/dist/hzdb-telemetry.d.ts.map +0 -1
package/dist/mcp-adapters.d.ts
CHANGED
|
@@ -41,6 +41,8 @@ export declare function getManagedMcpServerRegistry({ workspaceRoot, command, ar
|
|
|
41
41
|
export declare function mergeJsonConfig(filePath: string, serverEntries: Record<string, unknown>, jsonKey: string, managedKeys?: string[]): Promise<boolean>;
|
|
42
42
|
export declare function unmergeJsonConfig(filePath: string, serverKeys: string[], jsonKey: string, weCreatedFile: boolean): Promise<void>;
|
|
43
43
|
export declare function mergeTomlConfig(filePath: string, serverEntries: StableMcpEntryMap, managedKeys?: string[]): Promise<boolean>;
|
|
44
|
+
export declare function mergeOpenCodeConfig(filePath: string, serverEntries: StableMcpEntryMap, managedKeys: string[]): Promise<boolean>;
|
|
45
|
+
export declare function unmergeOpenCodeConfig(filePath: string, managedKeys: string[], weCreatedFile: boolean): Promise<void>;
|
|
44
46
|
export declare function unmergeTomlConfig(filePath: string, weCreatedFile: boolean, serverKeys?: string[]): Promise<void>;
|
|
45
47
|
export declare function syncMcpAdapters({ workspaceRoot, tools, command, args, }: SyncMcpAdaptersOptions): Promise<{
|
|
46
48
|
workspaceRoot: string;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"mcp-adapters.d.ts","sourceRoot":"","sources":["../src/mcp-adapters.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,EAGL,KAAK,MAAM,EACZ,MAAM,uBAAuB,CAAC;AAK/B,UAAU,qBAAqB;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,KAAK,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;AAE/D,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,uBAAuB;IACtC,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAWD,eAAO,MAAM,uBAAuB,QAAwC,CAAC;AAC7E,eAAO,MAAM,uBAAuB,2BAA4B,CAAC;AACjE,eAAO,MAAM,yBAAyB,EAEjC,SAAS,MAAM,EAAE,CAAC;AACvB,eAAO,MAAM,uBAAuB,EAE/B,SAAS,MAAM,EAAE,CAAC;AACvB,eAAO,MAAM,qBAAqB,EAE7B,SAAS,MAAM,EAAE,CAAC;AACvB,eAAO,MAAM,4BAA4B,EAIpC,SAAS,MAAM,EAAE,CAAC;AA+BvB,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,CAKT;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,OAAO,CAET;
|
|
1
|
+
{"version":3,"file":"mcp-adapters.d.ts","sourceRoot":"","sources":["../src/mcp-adapters.ts"],"names":[],"mappings":"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"}
|
package/dist/mcp-stdio.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"mcp-stdio.d.ts","sourceRoot":"","sources":["../src/mcp-stdio.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,
|
|
1
|
+
{"version":3,"file":"mcp-stdio.d.ts","sourceRoot":"","sources":["../src/mcp-stdio.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,OAAO,EAKL,KAAK,cAAc,EACpB,MAAM,uBAAuB,CAAC;AAW/B,MAAM,WAAW,iCAAiC;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;CACtD;AAyID,wBAAsB,0BAA0B,CAAC,EAC/C,UAAoB,EACpB,OAAiB,EACjB,cAAc,GACf,EAAE,iCAAiC,GAAG,OAAO,CAAC,IAAI,CAAC,CAsKnD"}
|
|
@@ -5,4 +5,4 @@
|
|
|
5
5
|
* LICENSE file in the root directory of this source tree.
|
|
6
6
|
*/
|
|
7
7
|
export declare function reportToolCall(toolName: string, success: boolean, durationMs: number, error?: string, sessionId?: string, clientVersion?: string): void;
|
|
8
|
-
//# sourceMappingURL=
|
|
8
|
+
//# sourceMappingURL=metavr-telemetry.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"metavr-telemetry.d.ts","sourceRoot":"","sources":["../src/metavr-telemetry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAmCH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,UAAU,EAAE,MAAM,EAClB,KAAK,CAAC,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,EAClB,aAAa,CAAC,EAAE,MAAM,GACrB,IAAI,CAkBN"}
|
|
@@ -4,22 +4,29 @@
|
|
|
4
4
|
* This source code is licensed under the MIT license found in the
|
|
5
5
|
* LICENSE file in the root directory of this source tree.
|
|
6
6
|
*/
|
|
7
|
-
export type AiTool = 'claude' | 'cursor' | 'copilot' | 'codex';
|
|
7
|
+
export type AiTool = 'claude' | 'cursor' | 'copilot' | 'codex' | 'opencode';
|
|
8
8
|
export type JsonSchema = {
|
|
9
9
|
type?: string;
|
|
10
10
|
description?: string;
|
|
11
11
|
enum?: string[];
|
|
12
12
|
oneOf?: JsonSchema[];
|
|
13
|
+
anyOf?: JsonSchema[];
|
|
14
|
+
not?: JsonSchema;
|
|
13
15
|
items?: JsonSchema;
|
|
14
16
|
properties?: Record<string, JsonSchema>;
|
|
15
17
|
required?: string[];
|
|
16
18
|
minimum?: number;
|
|
19
|
+
exclusiveMinimum?: number;
|
|
17
20
|
maximum?: number;
|
|
21
|
+
minItems?: number;
|
|
22
|
+
maxItems?: number;
|
|
23
|
+
pattern?: string;
|
|
24
|
+
additionalProperties?: boolean | JsonSchema;
|
|
18
25
|
};
|
|
19
26
|
export interface McpConfigTarget {
|
|
20
27
|
file: string;
|
|
21
28
|
jsonKey: string | null;
|
|
22
|
-
format: 'json' | 'toml';
|
|
29
|
+
format: 'json' | 'toml' | 'opencode';
|
|
23
30
|
}
|
|
24
31
|
export interface McpToolDefinition {
|
|
25
32
|
name: string;
|
|
@@ -33,9 +40,17 @@ export interface RuntimeOperationDefinition {
|
|
|
33
40
|
cliPath: [string, string] | string[];
|
|
34
41
|
mcpName: string;
|
|
35
42
|
wsMethod: string;
|
|
43
|
+
target?: RuntimePageTarget;
|
|
36
44
|
description: string;
|
|
37
45
|
inputSchema: JsonSchema;
|
|
38
46
|
}
|
|
47
|
+
export type RuntimePageRole = 'app' | 'editor' | 'preview';
|
|
48
|
+
export interface RuntimePageTarget {
|
|
49
|
+
role?: RuntimePageRole;
|
|
50
|
+
pageId?: string;
|
|
51
|
+
tabGeneration?: number;
|
|
52
|
+
sceneSessionId?: string;
|
|
53
|
+
}
|
|
39
54
|
export declare const IWSDK_PROJECT_STATE_DIR = ".iwsdk";
|
|
40
55
|
export declare const IWSDK_RUNTIME_STATE_DIR = ".iwsdk/runtime";
|
|
41
56
|
export declare const IWSDK_RUNTIME_LOGS_DIR = ".iwsdk/runtime/logs";
|
|
@@ -50,7 +65,7 @@ export interface RuntimeIssueInfo {
|
|
|
50
65
|
message: string;
|
|
51
66
|
at: string;
|
|
52
67
|
}
|
|
53
|
-
export type RuntimeBrowserStatus = 'launching' | 'waiting_for_connection' | 'connected' | 'disconnected' | 'launch_failed';
|
|
68
|
+
export type RuntimeBrowserStatus = 'not_launched' | 'launching' | 'waiting_for_connection' | 'connected' | 'disconnected' | 'launch_failed';
|
|
54
69
|
export interface RuntimeBrowserState {
|
|
55
70
|
status: RuntimeBrowserStatus;
|
|
56
71
|
connected: boolean;
|
|
@@ -98,6 +113,7 @@ export interface WorkspaceRuntimeState {
|
|
|
98
113
|
starting: boolean;
|
|
99
114
|
browserConnected: boolean;
|
|
100
115
|
browserCommandReady: boolean;
|
|
116
|
+
browserIssue?: RuntimeIssueInfo;
|
|
101
117
|
session: RuntimeSession | null;
|
|
102
118
|
launch: LaunchMetadata | null;
|
|
103
119
|
}
|
|
@@ -106,11 +122,22 @@ export declare function hasRuntimeBrowserCommandReadyContract(session: RuntimeBr
|
|
|
106
122
|
export declare function isRuntimeBrowserCommandReady(session: RuntimeBrowserStatusSession | null | undefined): boolean;
|
|
107
123
|
export declare const SUPPORTED_AI_TOOLS: AiTool[];
|
|
108
124
|
export declare const MCP_CONFIG_TARGETS: Record<AiTool, McpConfigTarget>;
|
|
125
|
+
export declare const SCENE_MCP_TOOL_NAMES: readonly ["scene_open", "scene_render_file", "scene_flatten_file", "scene_get_state", "scene_get_capabilities", "scene_screenshot", "scene_select", "scene_set_camera", "scene_set_preview_visibility", "scene_measure_image_regions"];
|
|
126
|
+
export declare const APP_RUNTIME_SCENE_MCP_TOOL_NAMES: readonly ["scene_get_render_stats", "scene_get_runtime_hierarchy", "scene_get_object_transform"];
|
|
109
127
|
export declare const RUNTIME_MCP_TOOLS: McpToolDefinition[];
|
|
110
128
|
export declare const RUNTIME_TOOL_TO_METHOD: Record<string, string>;
|
|
111
129
|
export declare const RUNTIME_CLI_PATHS: Record<string, string[]>;
|
|
130
|
+
export declare const SCENE_EDITOR_MCP_TOOL_NAMES: readonly ["scene_get_capabilities", "scene_get_state", "scene_select", "scene_set_camera", "scene_screenshot", "scene_set_preview_visibility", "scene_measure_image_regions", "ui_list_assets", "ui_render_preview"];
|
|
131
|
+
export declare const SCENE_FILE_MCP_TOOL_NAMES: readonly ["scene_open", "scene_render_file", "scene_flatten_file"];
|
|
132
|
+
export declare const PROJECT_ASSET_MCP_TOOL_NAMES: readonly [];
|
|
133
|
+
export declare const REVIEW_EVIDENCE_MCP_TOOL_NAMES: readonly [];
|
|
134
|
+
export declare const WORKSPACE_MCP_TOOL_NAMES: readonly [];
|
|
112
135
|
export declare const RUNTIME_OPERATIONS: RuntimeOperationDefinition[];
|
|
113
136
|
export declare function getRuntimeOperationByToolName(toolName: string): RuntimeOperationDefinition | undefined;
|
|
114
137
|
export declare function getRuntimeOperationByCliPath(domain: string, action: string): RuntimeOperationDefinition | undefined;
|
|
138
|
+
export declare function resolveRuntimeOperationRequest(operation: RuntimeOperationDefinition, params: unknown): {
|
|
139
|
+
params: unknown;
|
|
140
|
+
target?: RuntimePageTarget;
|
|
141
|
+
};
|
|
115
142
|
export {};
|
|
116
143
|
//# sourceMappingURL=runtime-contract.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"runtime-contract.d.ts","sourceRoot":"","sources":["../src/runtime-contract.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;
|
|
1
|
+
{"version":3,"file":"runtime-contract.d.ts","sourceRoot":"","sources":["../src/runtime-contract.ts"],"names":[],"mappings":"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"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"runtime-state.d.ts","sourceRoot":"","sources":["../src/runtime-state.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAML,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC3B,MAAM,uBAAuB,CAAC;
|
|
1
|
+
{"version":3,"file":"runtime-state.d.ts","sourceRoot":"","sources":["../src/runtime-state.ts"],"names":[],"mappings":"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"}
|
|
@@ -4,10 +4,11 @@
|
|
|
4
4
|
* This source code is licensed under the MIT license found in the
|
|
5
5
|
* LICENSE file in the root directory of this source tree.
|
|
6
6
|
*/
|
|
7
|
-
import { type RuntimeBrowserState, type RuntimeIssueCause, type RuntimeSession } from './runtime-contract.js';
|
|
7
|
+
import { type RuntimePageTarget, type RuntimeBrowserState, type RuntimeIssueCause, type RuntimeSession } from './runtime-contract.js';
|
|
8
8
|
type RuntimeCommandError = {
|
|
9
9
|
message?: string;
|
|
10
10
|
cause?: RuntimeIssueCause;
|
|
11
|
+
data?: Record<string, unknown>;
|
|
11
12
|
};
|
|
12
13
|
export interface RuntimeCommandResponse {
|
|
13
14
|
id?: string;
|
|
@@ -20,17 +21,20 @@ export interface SendRuntimeCommandOptions {
|
|
|
20
21
|
port: number;
|
|
21
22
|
method: string;
|
|
22
23
|
params?: unknown;
|
|
24
|
+
target?: RuntimePageTarget;
|
|
23
25
|
timeoutMs?: number;
|
|
24
26
|
runtimeSession?: RuntimeSession | null;
|
|
25
27
|
}
|
|
26
28
|
export declare class RuntimeCommandExecutionError extends Error {
|
|
27
29
|
issueCause?: RuntimeIssueCause;
|
|
28
30
|
browser?: RuntimeBrowserState;
|
|
31
|
+
details?: Record<string, unknown>;
|
|
29
32
|
constructor(message: string, options?: {
|
|
30
33
|
issueCause?: RuntimeIssueCause;
|
|
31
34
|
browser?: RuntimeBrowserState;
|
|
35
|
+
details?: Record<string, unknown>;
|
|
32
36
|
});
|
|
33
37
|
}
|
|
34
|
-
export declare function sendRuntimeCommand({ port, method, params, timeoutMs, runtimeSession, }: SendRuntimeCommandOptions): Promise<RuntimeCommandResponse>;
|
|
38
|
+
export declare function sendRuntimeCommand({ port, method, params, target, timeoutMs, runtimeSession, }: SendRuntimeCommandOptions): Promise<RuntimeCommandResponse>;
|
|
35
39
|
export {};
|
|
36
40
|
//# sourceMappingURL=runtime-transport.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"runtime-transport.d.ts","sourceRoot":"","sources":["../src/runtime-transport.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACpB,MAAM,uBAAuB,CAAC;
|
|
1
|
+
{"version":3,"file":"runtime-transport.d.ts","sourceRoot":"","sources":["../src/runtime-transport.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACpB,MAAM,uBAAuB,CAAC;AAK/B,KAAK,mBAAmB,GAAG;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,CAAC;AAGF,MAAM,WAAW,sBAAsB;IACrC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,mBAAmB,CAAC;CAC7B;AAED,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;CACxC;AAED,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAGhC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QACP,UAAU,CAAC,EAAE,iBAAiB,CAAC;QAC/B,OAAO,CAAC,EAAE,mBAAmB,CAAC;QAC9B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC9B;CAQT;AAmmBD,wBAAsB,kBAAkB,CAAC,EACvC,IAAI,EACJ,MAAM,EACN,MAAM,EACN,MAAM,EACN,SAAiB,EACjB,cAAc,GACf,EAAE,yBAAyB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAwB7D"}
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
# IWSDK project
|
|
2
|
+
|
|
3
|
+
A Vite + TypeScript or JavaScript app, but several things do **not** work the way
|
|
4
|
+
a normal Vite project works. Read this section before assuming anything.
|
|
5
|
+
|
|
6
|
+
Deeper material is installed in each selected harness's native path-scoped rule
|
|
7
|
+
format. Harnesses that use `AGENTS.md` also receive equivalent nested files near
|
|
8
|
+
the code they govern. Read the applicable scoped instructions before working in
|
|
9
|
+
that area.
|
|
10
|
+
|
|
11
|
+
## What is not standard Vite
|
|
12
|
+
|
|
13
|
+
**`iwsdk.config.json` is the project authority, not `vite.config.ts`.** It selects
|
|
14
|
+
the active scene, the asset module, the component module, and all XR/world
|
|
15
|
+
features. `vite.config.ts` only wires the plugin. Editing `iwsdk.config.json`
|
|
16
|
+
restarts Vite in place; the managed window remains open and its command bridges
|
|
17
|
+
reconnect automatically. Wait for `npx iwsdk dev status` to report
|
|
18
|
+
`browserCommandReady: true` before issuing browser-backed commands.
|
|
19
|
+
|
|
20
|
+
**`virtual:iwsdk-project` is a virtual module**, not a file. `src/index.ts` or
|
|
21
|
+
`src/index.js` imports it and passes it whole to `World.create()`. Do not
|
|
22
|
+
hand-build that options object.
|
|
23
|
+
|
|
24
|
+
**The dev server is CLI-managed.** Use `npx iwsdk dev up` (or `npm run dev`), not
|
|
25
|
+
`vite`. It launches a managed browser that hosts the MCP command bridge.
|
|
26
|
+
`--no-open` intentionally starts only the server: status reports
|
|
27
|
+
`browser.status: "not_launched"`, and browser-backed commands fail immediately
|
|
28
|
+
with `browser_not_launched` plus restart guidance. One managed window hosts two
|
|
29
|
+
roles, editor and runtime.
|
|
30
|
+
|
|
31
|
+
**`src/assets.ts`/`src/assets.js` is evaluated twice, in two different JS
|
|
32
|
+
realms** — once by the app runtime, once by the editor. It must be deterministic
|
|
33
|
+
and side-effect free: no `World`, no DOM, no timers, no reliance on shared object
|
|
34
|
+
identity.
|
|
35
|
+
|
|
36
|
+
**Static geometry lives in TypeScript, composition lives in JSON.** Scene JSON
|
|
37
|
+
never declares URLs, geometry or materials — only manifest IDs.
|
|
38
|
+
|
|
39
|
+
**Components must be declared in a system-free module** and exported from
|
|
40
|
+
`src/components.ts`/`src/components.js` via `defineComponents()`. The editor
|
|
41
|
+
imports that same manifest to build its inspector, so a component that is not in
|
|
42
|
+
it cannot be authored in scenes.
|
|
43
|
+
|
|
44
|
+
**Import Three.js from `@iwsdk/core`, never from `three`.** `@iwsdk/core`
|
|
45
|
+
re-exports all of Three; importing `three` directly creates a duplicate instance
|
|
46
|
+
and subtle breakage. Exception: `import type { GLTF } from 'three/addons/...'`.
|
|
47
|
+
|
|
48
|
+
## Traps that produce silent failures
|
|
49
|
+
|
|
50
|
+
| Trap | Symptom | Fix |
|
|
51
|
+
| ------------------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
|
|
52
|
+
| `locomotion: true` with no `LocomotionEnvironment` on a floor | player falls through the world | add the component to a walkable surface |
|
|
53
|
+
| Scene origin left occupied | player spawns inside your geometry | the player origin is `0,0,0` unless the scene authors `player.transform` |
|
|
54
|
+
| Scene JSON with `imports` | authoring preview works, but editable open and runtime load are rejected | run `npx iwsdk scene flatten` once, then edit the flat output |
|
|
55
|
+
| `entity.destroy()` | GPU memory leaked | use `entity.dispose()` |
|
|
56
|
+
| `setValue` on a Vec2/Vec3/Vec4/Color field | throws in elics 3.4.x | use `entity.getVectorView(...)` |
|
|
57
|
+
| Environment component on a non-root entity | silently ignored | `DomeGradient`/`IBLGradient` go on the level root only |
|
|
58
|
+
| Environment prop changed without `_needsUpdate` | change ignored | set `_needsUpdate` after writing |
|
|
59
|
+
| `ScreenSpace` given numbers | clamped with a console warning | it takes CSS strings: `'400px'`, `'25vw'` |
|
|
60
|
+
| `@iwsdk/reference` MCP tools in an old or `--no-install` app | queries report warmup required | run `npx iwsdk reference warmup`; fresh installed scaffolds do this during creation |
|
|
61
|
+
|
|
62
|
+
## Verify before you claim it works
|
|
63
|
+
|
|
64
|
+
**Always `npx tsc --noEmit` before testing.** Type errors stop systems
|
|
65
|
+
initialising without necessarily logging anything in the browser.
|
|
66
|
+
|
|
67
|
+
Then check the right status for the task — these are not interchangeable:
|
|
68
|
+
|
|
69
|
+
- scene/editor work → `scene_get_state`
|
|
70
|
+
- XR device or session actions → `xr_get_session_status`
|
|
71
|
+
- server readiness → `npx iwsdk dev status` (XR availability is not a server signal)
|
|
72
|
+
|
|
73
|
+
When something is missing but the console is clean: call
|
|
74
|
+
`browser_get_console_logs` with only `count` (a `level` filter hides errors), then
|
|
75
|
+
`ecs_find_entities` to confirm the entity exists and carries the components you
|
|
76
|
+
expect.
|
|
77
|
+
|
|
78
|
+
The non-obvious part is which observation proves what: the **editor** render does
|
|
79
|
+
not run application systems, so anything driven by a system must be verified with
|
|
80
|
+
`browser_screenshot` (runtime), not `scene_screenshot` (editor).
|
|
81
|
+
|
|
82
|
+
## MCP and CLI are one surface, not two
|
|
83
|
+
|
|
84
|
+
Nearly every capability exists both ways — `scene_render_file` and
|
|
85
|
+
`npx iwsdk scene render-file`, `ecs_find_entities` and `npx iwsdk ecs find`.
|
|
86
|
+
Discover CLI actions with the bare domain or domain help (`npx iwsdk scene` or
|
|
87
|
+
`npx iwsdk scene --help`); both list that domain's actions.
|
|
88
|
+
|
|
89
|
+
**The CLI is not a fallback for a dead bridge.** Both routes drive the same
|
|
90
|
+
managed browser, so when `dev status` reports `browserConnected: false`,
|
|
91
|
+
every scene/ecs/xr/browser/ui command fails either way. Only `dev status`,
|
|
92
|
+
`dev logs` and `reference status` work without a browser.
|
|
93
|
+
|
|
94
|
+
Choose by the shape of the call, not by availability:
|
|
95
|
+
|
|
96
|
+
- **MCP** for one-off calls, and whenever you want the image returned inline.
|
|
97
|
+
- **CLI** when you need to loop or script — rendering six views, or sampling a
|
|
98
|
+
value twice to measure a rate — or when the response is big enough to be worth
|
|
99
|
+
filtering before it reaches context. A render of a scene containing an
|
|
100
|
+
instanced pattern returns an id for every expanded instance.
|
|
101
|
+
|
|
102
|
+
CLI `--output-file` returns a **different payload shape** from the plain call:
|
|
103
|
+
the result nests under `data.result` instead of `data`, and `renderStats` and the
|
|
104
|
+
hashes are dropped. If you need a hash or triangle count, omit `--output-file`
|
|
105
|
+
and filter the JSON instead.
|
|
106
|
+
|
|
107
|
+
## Skills
|
|
108
|
+
|
|
109
|
+
Scene composition, UI authoring, physics, depth occlusion, grab and ray
|
|
110
|
+
interaction testing, ECS frame-stepping, and end-to-end planning each have a
|
|
111
|
+
project skill in the selected harness's standard skill directory. Their
|
|
112
|
+
descriptions handle routing, so they are not restated here.
|
|
113
|
+
|
|
114
|
+
The failure worth guarding against is improvising a domain that already has a
|
|
115
|
+
skill because the naive approach looks tractable. Before hand-authoring scene
|
|
116
|
+
JSON, a UIKitML panel, or a physics body, invoke the skill.
|
|
117
|
+
|
|
118
|
+
## Layout
|
|
119
|
+
|
|
120
|
+
```
|
|
121
|
+
iwsdk.config.json project authority: scene, assets, components, world, dev
|
|
122
|
+
src/index.ts|js World.create() + explicit system registration
|
|
123
|
+
src/assets.ts|js defineAssets() — shared runtime/editor catalog
|
|
124
|
+
src/components.ts|js defineComponents() — shared runtime/editor catalog
|
|
125
|
+
src/scene-assets/ *.scene-asset.ts|js — parentless Object3D prototypes
|
|
126
|
+
public/scenes/ *.iwsdk.scene.json — composition only
|
|
127
|
+
public/ui/ *.uikitml — runtime-loaded panels
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
No barrel `index.ts` files. Keep component declarations free of system, DOM and
|
|
131
|
+
renderer imports; systems import the declarations, never the reverse.
|
|
132
|
+
|
|
133
|
+
## Conventions
|
|
134
|
+
|
|
135
|
+
- Systems use queries, never manually tracked entity arrays.
|
|
136
|
+
- Never allocate in `update()`. Allocate in `init()` as class properties.
|
|
137
|
+
- Prefer `queries.x.subscribe('qualify', ...)` over polling state each frame.
|
|
138
|
+
- Register every subscription teardown in `this.cleanupFuncs`.
|
|
139
|
+
- Use `signal.peek()` in `update()`; `.value` adds per-frame subscription overhead.
|
|
140
|
+
- Load assets through `AssetManager` / the manifest, never a raw `GLTFLoader`.
|
|
141
|
+
- Create entities with `world.createTransformEntity(...)`, never `scene.add()`.
|
|
142
|
+
- Use the `RayInteractable` component, never a manual `Raycaster`.
|
|
143
|
+
- VR targets 72–90 fps: 11–14 ms per frame. Treat per-frame allocation as a bug.
|
|
144
|
+
|
|
145
|
+
## Deep reference
|
|
146
|
+
|
|
147
|
+
Harness-native scoped rules cover `public/scenes/**`, `public/ui/**`,
|
|
148
|
+
`src/assets.ts`, `src/scene-assets/**`, and `src/**/*.ts`. `AGENTS.md`-based
|
|
149
|
+
harnesses receive nested instruction files; Cursor and Copilot receive their
|
|
150
|
+
native rule formats. Skill procedures live in the selected harness's project
|
|
151
|
+
skill directory and state when they apply.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@iwsdk/cli",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.1",
|
|
4
4
|
"description": "Runtime-first CLI for IWSDK dev servers, adapters, and MCP access",
|
|
5
5
|
"private": false,
|
|
6
6
|
"type": "module",
|
|
@@ -28,6 +28,7 @@
|
|
|
28
28
|
},
|
|
29
29
|
"files": [
|
|
30
30
|
"dist",
|
|
31
|
+
"guidance",
|
|
31
32
|
"README.md"
|
|
32
33
|
],
|
|
33
34
|
"keywords": [
|
|
@@ -51,15 +52,15 @@
|
|
|
51
52
|
"node": ">=20.19.0 <21.0.0-0 || >=22.12.0 <23.0.0-0 || >=24.0.0"
|
|
52
53
|
},
|
|
53
54
|
"devDependencies": {
|
|
54
|
-
"@modelcontextprotocol/sdk": "^1.
|
|
55
|
+
"@modelcontextprotocol/sdk": "^1.30.0",
|
|
55
56
|
"@types/ws": "^8.5.13",
|
|
56
|
-
"vitest": "^4.
|
|
57
|
-
"ws": "^8.
|
|
57
|
+
"vitest": "^4.1.10",
|
|
58
|
+
"ws": "^8.21.1"
|
|
58
59
|
},
|
|
59
60
|
"scripts": {
|
|
60
61
|
"build": "tsc -p tsconfig.json --emitDeclarationOnly && rollup -c",
|
|
61
62
|
"clean": "rm -rf dist",
|
|
62
|
-
"test": "pnpm build && vitest run",
|
|
63
|
+
"test": "corepack pnpm@10.18.3 build && vitest run",
|
|
63
64
|
"test:watch": "vitest"
|
|
64
65
|
}
|
|
65
66
|
}
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"hzdb-telemetry.d.ts","sourceRoot":"","sources":["../src/hzdb-telemetry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAkBH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,OAAO,EAChB,UAAU,EAAE,MAAM,EAClB,KAAK,CAAC,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,EAClB,aAAa,CAAC,EAAE,MAAM,GACrB,IAAI,CAkBN"}
|