@iwsdk/cli 1.0.0 → 1.0.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.
@@ -1 +1 @@
1
- {"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/commands/mcp.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAM7E,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,UAAU,EACnB,EAAE,EAAE,aAAa,GAChB,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAyC9B;AAED,wBAAsB,cAAc,CAClC,OAAO,EAAE,UAAU,EACnB,EAAE,EAAE,aAAa,GAChB,OAAO,CAAC,IAAI,CAAC,CAef"}
1
+ {"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/commands/mcp.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAM7E,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,UAAU,EACnB,EAAE,EAAE,aAAa,GAChB,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAyC9B;AAED,wBAAsB,cAAc,CAClC,OAAO,EAAE,UAAU,EACnB,EAAE,EAAE,aAAa,GAChB,OAAO,CAAC,IAAI,CAAC,CAcf"}
@@ -1 +1 @@
1
- {"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/commands/runtime.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EACZ,UAAU,EACV,aAAa,EACd,MAAM,iBAAiB,CAAC;AAmKzB,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,EAAE,UAAU,EACnB,EAAE,EAAE,aAAa,GAChB,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,YAAY,CAAC,CAsG7C"}
1
+ {"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/commands/runtime.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EACZ,UAAU,EACV,aAAa,EACd,MAAM,iBAAiB,CAAC;AAyKzB,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,EAAE,UAAU,EACnB,EAAE,EAAE,aAAa,GAChB,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,YAAY,CAAC,CAoB7C"}
package/dist/index.js CHANGED
@@ -3897,6 +3897,14 @@ function getRuntimeUrls(session) {
3897
3897
  network: session?.networkUrls ?? [],
3898
3898
  };
3899
3899
  }
3900
+ /** Thrown when a command finds no IWSDK app, or no runtime running for it. */
3901
+ class WorkspaceResolutionError extends Error {
3902
+ constructor(message, reason) {
3903
+ super(message);
3904
+ this.reason = reason;
3905
+ this.name = 'WorkspaceResolutionError';
3906
+ }
3907
+ }
3900
3908
  function formatMissingRuntimeMessage(workspaceRoot) {
3901
3909
  return `No running IWSDK runtime found for ${workspaceRoot}. Start the dev server with "iwsdk dev up".`;
3902
3910
  }
@@ -3904,14 +3912,14 @@ async function resolveWorkspaceRoot({ cwd = process.cwd(), workspace, requireRun
3904
3912
  const basePath = workspace ?? cwd;
3905
3913
  const workspaceRoot = findNearestIwsdkAppRoot(basePath);
3906
3914
  if (!workspaceRoot) {
3907
- throw new Error(`No IWSDK app found at or above: ${workspace ?? cwd}. Run this command inside an IWSDK app.`);
3915
+ throw new WorkspaceResolutionError(`No IWSDK app found at or above: ${workspace ?? cwd}. Run this command inside an IWSDK app.`, 'no_app');
3908
3916
  }
3909
3917
  if (!requireRunning) {
3910
3918
  return workspaceRoot;
3911
3919
  }
3912
3920
  const session = await getRuntimeSession(workspaceRoot);
3913
3921
  if (!session) {
3914
- throw new Error(formatMissingRuntimeMessage(workspaceRoot));
3922
+ throw new WorkspaceResolutionError(formatMissingRuntimeMessage(workspaceRoot), 'no_runtime');
3915
3923
  }
3916
3924
  return workspaceRoot;
3917
3925
  }
@@ -28134,7 +28142,7 @@ function metaVrTelemetry(args, clientVersion) {
28134
28142
  return;
28135
28143
  }
28136
28144
  const globalArgs = ['xxiwsdk'];
28137
- if (clientVersion) {
28145
+ {
28138
28146
  globalArgs.push('--client-version', clientVersion);
28139
28147
  }
28140
28148
  const child = spawn(process.execPath, [entrypoint, ...globalArgs, ...args], {
@@ -28156,7 +28164,9 @@ function reportToolCall(toolName, success, durationMs, error, sessionId, clientV
28156
28164
  args.push('--failure');
28157
28165
  }
28158
28166
  if (error) {
28159
- args.push('--error', error);
28167
+ // Attached, so MetaVR accepts messages that start with "-", such as
28168
+ // "--input-json must be valid JSON".
28169
+ args.push(`--error=${error}`);
28160
28170
  }
28161
28171
  if (sessionId) {
28162
28172
  args.push('--session-id', sessionId);
@@ -28164,6 +28174,69 @@ function reportToolCall(toolName, success, durationMs, error, sessionId, clientV
28164
28174
  metaVrTelemetry(args, clientVersion);
28165
28175
  }
28166
28176
 
28177
+ const CLI_VERSION = "1.0.1";
28178
+
28179
+ /**
28180
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
28181
+ *
28182
+ * This source code is licensed under the MIT license found in the
28183
+ * LICENSE file in the root directory of this source tree.
28184
+ */
28185
+ const ISSUE_CAUSES = {
28186
+ browser_not_ready: true,
28187
+ browser_not_launched: true,
28188
+ browser_launch_failed: true,
28189
+ connection_lost: true,
28190
+ permission_denied: true,
28191
+ browser_relaunched: true,
28192
+ tab_throttled: true,
28193
+ open_failed: true,
28194
+ };
28195
+ const KNOWN_ISSUE_CAUSES = new Set(Object.keys(ISSUE_CAUSES));
28196
+ /** Maps an error from resolving or running an operation to its reason. */
28197
+ function getRuntimeFailureReason(error) {
28198
+ if (error instanceof WorkspaceResolutionError) {
28199
+ return error.reason;
28200
+ }
28201
+ if (error instanceof RuntimeCommandExecutionError) {
28202
+ // The runtime forwards a string cause from whatever the app threw, so
28203
+ // only the known causes are reported.
28204
+ const cause = error.issueCause;
28205
+ return cause && KNOWN_ISSUE_CAUSES.has(cause) ? cause : 'runtime_error';
28206
+ }
28207
+ return 'unknown';
28208
+ }
28209
+ /**
28210
+ * Records one runtime operation, whether the MCP server or the CLI ran it.
28211
+ * Both report the operation under its MCP tool name, so the same operation
28212
+ * produces the same event from either surface. Only the first outcome is
28213
+ * reported: a failure while presenting a successful result does not record
28214
+ * the operation a second time.
28215
+ */
28216
+ function startRuntimeOperationTelemetry(operation) {
28217
+ const startTime = Date.now();
28218
+ let sessionId;
28219
+ let settled = false;
28220
+ const settle = (success, error) => {
28221
+ if (settled) {
28222
+ return;
28223
+ }
28224
+ settled = true;
28225
+ reportToolCall(operation.mcpName, success, Date.now() - startTime, error, sessionId, CLI_VERSION);
28226
+ };
28227
+ return {
28228
+ attachSession(session) {
28229
+ sessionId = session.sessionId;
28230
+ },
28231
+ succeed() {
28232
+ settle(true);
28233
+ },
28234
+ fail(reason) {
28235
+ settle(false, reason);
28236
+ },
28237
+ };
28238
+ }
28239
+
28167
28240
  /**
28168
28241
  * Copyright (c) Meta Platforms, Inc. and affiliates.
28169
28242
  *
@@ -28353,7 +28426,7 @@ function createErrorContent(message, options = {}) {
28353
28426
  };
28354
28427
  return [{ type: 'text', text: JSON.stringify(payload, null, 2) }];
28355
28428
  }
28356
- async function startRuntimeMcpStdioServer({ serverName = 'iwsdk', version = '1.0.0', resolveSession, }) {
28429
+ async function startRuntimeMcpStdioServer({ serverName = 'iwsdk', version = CLI_VERSION, resolveSession, }) {
28357
28430
  const tabTracker = createTabTracker();
28358
28431
  const server = new Server({
28359
28432
  name: serverName,
@@ -28369,20 +28442,34 @@ async function startRuntimeMcpStdioServer({ serverName = 'iwsdk', version = '1.0
28369
28442
  server.setRequestHandler(CallToolRequestSchema, async (request) => {
28370
28443
  const { name, arguments: args } = request.params;
28371
28444
  const operation = RUNTIME_OPERATIONS.find((entry) => entry.mcpName === name);
28372
- const startTime = Date.now();
28373
28445
  if (!operation) {
28374
28446
  return {
28375
28447
  content: [{ type: 'text', text: `Unknown tool: ${name}` }],
28376
28448
  isError: true,
28377
28449
  };
28378
28450
  }
28451
+ const telemetry = startRuntimeOperationTelemetry(operation);
28452
+ // Validate before looking up the runtime, as the CLI does, so invalid
28453
+ // input fails the same way whether or not a runtime is running.
28454
+ let command;
28455
+ try {
28456
+ command = resolveRuntimeOperationRequest(operation, args);
28457
+ }
28458
+ catch (error) {
28459
+ const message = error instanceof Error ? error.message : String(error);
28460
+ telemetry.fail('invalid_input');
28461
+ return {
28462
+ content: createErrorContent(message),
28463
+ isError: true,
28464
+ };
28465
+ }
28379
28466
  let session;
28380
28467
  try {
28381
28468
  session = await resolveSession();
28382
28469
  }
28383
28470
  catch (error) {
28384
28471
  const message = error instanceof Error ? error.message : String(error);
28385
- reportToolCall(name, false, Date.now() - startTime, message.slice(0, 30), undefined, version);
28472
+ telemetry.fail(getRuntimeFailureReason(error));
28386
28473
  return {
28387
28474
  content: [
28388
28475
  { type: 'text', text: `Failed to resolve IWSDK runtime: ${message}` },
@@ -28391,7 +28478,7 @@ async function startRuntimeMcpStdioServer({ serverName = 'iwsdk', version = '1.0
28391
28478
  };
28392
28479
  }
28393
28480
  if (!session) {
28394
- reportToolCall(name, false, Date.now() - startTime, 'no active runtime', undefined, version);
28481
+ telemetry.fail('no_runtime');
28395
28482
  return {
28396
28483
  content: [
28397
28484
  {
@@ -28402,8 +28489,8 @@ async function startRuntimeMcpStdioServer({ serverName = 'iwsdk', version = '1.0
28402
28489
  isError: true,
28403
28490
  };
28404
28491
  }
28492
+ telemetry.attachSession(session);
28405
28493
  try {
28406
- const command = resolveRuntimeOperationRequest(operation, args);
28407
28494
  const rawResponse = await sendRuntimeCommand({
28408
28495
  port: session.port,
28409
28496
  method: operation.wsMethod,
@@ -28411,7 +28498,7 @@ async function startRuntimeMcpStdioServer({ serverName = 'iwsdk', version = '1.0
28411
28498
  target: command.target,
28412
28499
  runtimeSession: session,
28413
28500
  });
28414
- reportToolCall(name, true, Date.now() - startTime, undefined, session.sessionId, version);
28501
+ telemetry.succeed();
28415
28502
  // Managed browser status would misdescribe a headset's session.
28416
28503
  const normalizedResponse = name === 'xr_get_session_status' &&
28417
28504
  command.target?.deviceClass !== 'physical'
@@ -28473,7 +28560,7 @@ async function startRuntimeMcpStdioServer({ serverName = 'iwsdk', version = '1.0
28473
28560
  }
28474
28561
  catch (error) {
28475
28562
  const message = error instanceof Error ? error.message : String(error);
28476
- reportToolCall(name, false, Date.now() - startTime, message.slice(0, 30), session.sessionId, version);
28563
+ telemetry.fail(getRuntimeFailureReason(error));
28477
28564
  if (error instanceof RuntimeCommandExecutionError) {
28478
28565
  return {
28479
28566
  content: createErrorContent(message, {
@@ -28535,7 +28622,6 @@ async function handleMcpInspect(options, io) {
28535
28622
  async function handleMcpStdio(options, io) {
28536
28623
  await startRuntimeMcpStdioServer({
28537
28624
  serverName: 'iwsdk-runtime',
28538
- version: '1.0.0',
28539
28625
  resolveSession: async () => {
28540
28626
  const workspaceRoot = await resolveWorkspaceRoot({
28541
28627
  cwd: io.cwd,
@@ -28811,8 +28897,27 @@ async function handleRuntimeOperation(domain, action, options, io) {
28811
28897
  const available = RUNTIME_OPERATIONS.filter((entry) => entry.domain === domain).map((entry) => entry.action);
28812
28898
  throw new Error(`Unknown ${domain} command "${action}". Available: ${available.join(', ')}`);
28813
28899
  }
28814
- const parsedParams = resolveRuntimeParams(operation.mcpName, options);
28815
- const command = resolveRuntimeOperationRequest(operation, parsedParams);
28900
+ const telemetry = startRuntimeOperationTelemetry(operation);
28901
+ try {
28902
+ return await runRuntimeOperation(operation, options, io, telemetry);
28903
+ }
28904
+ catch (error) {
28905
+ telemetry.fail(getRuntimeFailureReason(error));
28906
+ throw error;
28907
+ }
28908
+ }
28909
+ async function runRuntimeOperation(operation, options, io, telemetry) {
28910
+ let command;
28911
+ let timeoutMs;
28912
+ try {
28913
+ const parsedParams = resolveRuntimeParams(operation.mcpName, options);
28914
+ command = resolveRuntimeOperationRequest(operation, parsedParams);
28915
+ timeoutMs = parseIntegerOption(options.timeout, '--timeout', getDefaultRuntimeCommandTimeoutMs(operation.wsMethod));
28916
+ }
28917
+ catch (error) {
28918
+ telemetry.fail('invalid_input');
28919
+ throw error;
28920
+ }
28816
28921
  const workspaceRoot = await resolveWorkspaceRoot({
28817
28922
  cwd: io.cwd,
28818
28923
  workspace: typeof options.workspace === 'string' ? options.workspace : undefined,
@@ -28820,14 +28925,16 @@ async function handleRuntimeOperation(domain, action, options, io) {
28820
28925
  });
28821
28926
  const session = await getRuntimeSession(workspaceRoot);
28822
28927
  if (!session) {
28928
+ telemetry.fail('no_runtime');
28823
28929
  throw new Error(formatMissingRuntimeMessage(workspaceRoot));
28824
28930
  }
28931
+ telemetry.attachSession(session);
28825
28932
  const sendOptions = {
28826
28933
  port: session.port,
28827
28934
  method: operation.wsMethod,
28828
28935
  params: command.params,
28829
28936
  target: command.target,
28830
- timeoutMs: parseIntegerOption(options.timeout, '--timeout', getDefaultRuntimeCommandTimeoutMs(operation.wsMethod)),
28937
+ timeoutMs,
28831
28938
  runtimeSession: session,
28832
28939
  };
28833
28940
  let rawResult;
@@ -28835,12 +28942,14 @@ async function handleRuntimeOperation(domain, action, options, io) {
28835
28942
  rawResult = await sendRuntimeCommand(sendOptions);
28836
28943
  }
28837
28944
  catch (error) {
28945
+ telemetry.fail(getRuntimeFailureReason(error));
28838
28946
  if (operation.mcpName === 'xr_accept_session' &&
28839
28947
  error instanceof RuntimeCommandExecutionError) {
28840
28948
  error.message = `${error.message} Configure world.xr.offer as "once" or "always" before running iwsdk xr enter.`;
28841
28949
  }
28842
28950
  throw error;
28843
28951
  }
28952
+ telemetry.succeed();
28844
28953
  // Managed browser status would misdescribe a headset's session.
28845
28954
  let result = operation.mcpName === 'xr_get_session_status' &&
28846
28955
  command.target?.deviceClass !== 'physical'