@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.
package/dist/cli.js CHANGED
@@ -2384,6 +2384,7 @@ function getUnsupportedNodeMessage(version, requiredRange) {
2384
2384
  }
2385
2385
 
2386
2386
  const NODE_ENGINE = ">=20.19.0 <21.0.0-0 || >=22.12.0 <23.0.0-0 || >=24.0.0";
2387
+ const CLI_VERSION = "1.0.1";
2387
2388
 
2388
2389
  /**
2389
2390
  * Copyright (c) Meta Platforms, Inc. and affiliates.
@@ -6264,6 +6265,14 @@ function getRuntimeUrls(session) {
6264
6265
  network: session?.networkUrls ?? [],
6265
6266
  };
6266
6267
  }
6268
+ /** Thrown when a command finds no IWSDK app, or no runtime running for it. */
6269
+ class WorkspaceResolutionError extends Error {
6270
+ constructor(message, reason) {
6271
+ super(message);
6272
+ this.reason = reason;
6273
+ this.name = 'WorkspaceResolutionError';
6274
+ }
6275
+ }
6267
6276
  function formatMissingRuntimeMessage(workspaceRoot) {
6268
6277
  return `No running IWSDK runtime found for ${workspaceRoot}. Start the dev server with "iwsdk dev up".`;
6269
6278
  }
@@ -6271,14 +6280,14 @@ async function resolveWorkspaceRoot({ cwd = process.cwd(), workspace, requireRun
6271
6280
  const basePath = workspace ?? cwd;
6272
6281
  const workspaceRoot = findNearestIwsdkAppRoot(basePath);
6273
6282
  if (!workspaceRoot) {
6274
- throw new Error(`No IWSDK app found at or above: ${workspace ?? cwd}. Run this command inside an IWSDK app.`);
6283
+ throw new WorkspaceResolutionError(`No IWSDK app found at or above: ${workspace ?? cwd}. Run this command inside an IWSDK app.`, 'no_app');
6275
6284
  }
6276
6285
  if (!requireRunning) {
6277
6286
  return workspaceRoot;
6278
6287
  }
6279
6288
  const session = await getRuntimeSession(workspaceRoot);
6280
6289
  if (!session) {
6281
- throw new Error(formatMissingRuntimeMessage(workspaceRoot));
6290
+ throw new WorkspaceResolutionError(formatMissingRuntimeMessage(workspaceRoot), 'no_runtime');
6282
6291
  }
6283
6292
  return workspaceRoot;
6284
6293
  }
@@ -30497,7 +30506,7 @@ function metaVrTelemetry(args, clientVersion) {
30497
30506
  return;
30498
30507
  }
30499
30508
  const globalArgs = ['xxiwsdk'];
30500
- if (clientVersion) {
30509
+ {
30501
30510
  globalArgs.push('--client-version', clientVersion);
30502
30511
  }
30503
30512
  const child = spawn(process.execPath, [entrypoint, ...globalArgs, ...args], {
@@ -30519,7 +30528,9 @@ function reportToolCall(toolName, success, durationMs, error, sessionId, clientV
30519
30528
  args.push('--failure');
30520
30529
  }
30521
30530
  if (error) {
30522
- args.push('--error', error);
30531
+ // Attached, so MetaVR accepts messages that start with "-", such as
30532
+ // "--input-json must be valid JSON".
30533
+ args.push(`--error=${error}`);
30523
30534
  }
30524
30535
  if (sessionId) {
30525
30536
  args.push('--session-id', sessionId);
@@ -30527,6 +30538,67 @@ function reportToolCall(toolName, success, durationMs, error, sessionId, clientV
30527
30538
  metaVrTelemetry(args, clientVersion);
30528
30539
  }
30529
30540
 
30541
+ /**
30542
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
30543
+ *
30544
+ * This source code is licensed under the MIT license found in the
30545
+ * LICENSE file in the root directory of this source tree.
30546
+ */
30547
+ const ISSUE_CAUSES = {
30548
+ browser_not_ready: true,
30549
+ browser_not_launched: true,
30550
+ browser_launch_failed: true,
30551
+ connection_lost: true,
30552
+ permission_denied: true,
30553
+ browser_relaunched: true,
30554
+ tab_throttled: true,
30555
+ open_failed: true,
30556
+ };
30557
+ const KNOWN_ISSUE_CAUSES = new Set(Object.keys(ISSUE_CAUSES));
30558
+ /** Maps an error from resolving or running an operation to its reason. */
30559
+ function getRuntimeFailureReason(error) {
30560
+ if (error instanceof WorkspaceResolutionError) {
30561
+ return error.reason;
30562
+ }
30563
+ if (error instanceof RuntimeCommandExecutionError) {
30564
+ // The runtime forwards a string cause from whatever the app threw, so
30565
+ // only the known causes are reported.
30566
+ const cause = error.issueCause;
30567
+ return cause && KNOWN_ISSUE_CAUSES.has(cause) ? cause : 'runtime_error';
30568
+ }
30569
+ return 'unknown';
30570
+ }
30571
+ /**
30572
+ * Records one runtime operation, whether the MCP server or the CLI ran it.
30573
+ * Both report the operation under its MCP tool name, so the same operation
30574
+ * produces the same event from either surface. Only the first outcome is
30575
+ * reported: a failure while presenting a successful result does not record
30576
+ * the operation a second time.
30577
+ */
30578
+ function startRuntimeOperationTelemetry(operation) {
30579
+ const startTime = Date.now();
30580
+ let sessionId;
30581
+ let settled = false;
30582
+ const settle = (success, error) => {
30583
+ if (settled) {
30584
+ return;
30585
+ }
30586
+ settled = true;
30587
+ reportToolCall(operation.mcpName, success, Date.now() - startTime, error, sessionId, CLI_VERSION);
30588
+ };
30589
+ return {
30590
+ attachSession(session) {
30591
+ sessionId = session.sessionId;
30592
+ },
30593
+ succeed() {
30594
+ settle(true);
30595
+ },
30596
+ fail(reason) {
30597
+ settle(false, reason);
30598
+ },
30599
+ };
30600
+ }
30601
+
30530
30602
  /**
30531
30603
  * Copyright (c) Meta Platforms, Inc. and affiliates.
30532
30604
  *
@@ -30716,7 +30788,7 @@ function createErrorContent(message, options = {}) {
30716
30788
  };
30717
30789
  return [{ type: 'text', text: JSON.stringify(payload, null, 2) }];
30718
30790
  }
30719
- async function startRuntimeMcpStdioServer({ serverName = 'iwsdk', version = '1.0.0', resolveSession, }) {
30791
+ async function startRuntimeMcpStdioServer({ serverName = 'iwsdk', version = CLI_VERSION, resolveSession, }) {
30720
30792
  const tabTracker = createTabTracker();
30721
30793
  const server = new Server({
30722
30794
  name: serverName,
@@ -30732,20 +30804,34 @@ async function startRuntimeMcpStdioServer({ serverName = 'iwsdk', version = '1.0
30732
30804
  server.setRequestHandler(CallToolRequestSchema, async (request) => {
30733
30805
  const { name, arguments: args } = request.params;
30734
30806
  const operation = RUNTIME_OPERATIONS.find((entry) => entry.mcpName === name);
30735
- const startTime = Date.now();
30736
30807
  if (!operation) {
30737
30808
  return {
30738
30809
  content: [{ type: 'text', text: `Unknown tool: ${name}` }],
30739
30810
  isError: true,
30740
30811
  };
30741
30812
  }
30813
+ const telemetry = startRuntimeOperationTelemetry(operation);
30814
+ // Validate before looking up the runtime, as the CLI does, so invalid
30815
+ // input fails the same way whether or not a runtime is running.
30816
+ let command;
30817
+ try {
30818
+ command = resolveRuntimeOperationRequest(operation, args);
30819
+ }
30820
+ catch (error) {
30821
+ const message = error instanceof Error ? error.message : String(error);
30822
+ telemetry.fail('invalid_input');
30823
+ return {
30824
+ content: createErrorContent(message),
30825
+ isError: true,
30826
+ };
30827
+ }
30742
30828
  let session;
30743
30829
  try {
30744
30830
  session = await resolveSession();
30745
30831
  }
30746
30832
  catch (error) {
30747
30833
  const message = error instanceof Error ? error.message : String(error);
30748
- reportToolCall(name, false, Date.now() - startTime, message.slice(0, 30), undefined, version);
30834
+ telemetry.fail(getRuntimeFailureReason(error));
30749
30835
  return {
30750
30836
  content: [
30751
30837
  { type: 'text', text: `Failed to resolve IWSDK runtime: ${message}` },
@@ -30754,7 +30840,7 @@ async function startRuntimeMcpStdioServer({ serverName = 'iwsdk', version = '1.0
30754
30840
  };
30755
30841
  }
30756
30842
  if (!session) {
30757
- reportToolCall(name, false, Date.now() - startTime, 'no active runtime', undefined, version);
30843
+ telemetry.fail('no_runtime');
30758
30844
  return {
30759
30845
  content: [
30760
30846
  {
@@ -30765,8 +30851,8 @@ async function startRuntimeMcpStdioServer({ serverName = 'iwsdk', version = '1.0
30765
30851
  isError: true,
30766
30852
  };
30767
30853
  }
30854
+ telemetry.attachSession(session);
30768
30855
  try {
30769
- const command = resolveRuntimeOperationRequest(operation, args);
30770
30856
  const rawResponse = await sendRuntimeCommand({
30771
30857
  port: session.port,
30772
30858
  method: operation.wsMethod,
@@ -30774,7 +30860,7 @@ async function startRuntimeMcpStdioServer({ serverName = 'iwsdk', version = '1.0
30774
30860
  target: command.target,
30775
30861
  runtimeSession: session,
30776
30862
  });
30777
- reportToolCall(name, true, Date.now() - startTime, undefined, session.sessionId, version);
30863
+ telemetry.succeed();
30778
30864
  // Managed browser status would misdescribe a headset's session.
30779
30865
  const normalizedResponse = name === 'xr_get_session_status' &&
30780
30866
  command.target?.deviceClass !== 'physical'
@@ -30836,7 +30922,7 @@ async function startRuntimeMcpStdioServer({ serverName = 'iwsdk', version = '1.0
30836
30922
  }
30837
30923
  catch (error) {
30838
30924
  const message = error instanceof Error ? error.message : String(error);
30839
- reportToolCall(name, false, Date.now() - startTime, message.slice(0, 30), session.sessionId, version);
30925
+ telemetry.fail(getRuntimeFailureReason(error));
30840
30926
  if (error instanceof RuntimeCommandExecutionError) {
30841
30927
  return {
30842
30928
  content: createErrorContent(message, {
@@ -30898,7 +30984,6 @@ async function handleMcpInspect(options, io) {
30898
30984
  async function handleMcpStdio(options, io) {
30899
30985
  await startRuntimeMcpStdioServer({
30900
30986
  serverName: 'iwsdk-runtime',
30901
- version: '1.0.0',
30902
30987
  resolveSession: async () => {
30903
30988
  const workspaceRoot = await resolveWorkspaceRoot({
30904
30989
  cwd: io.cwd,
@@ -31174,8 +31259,27 @@ async function handleRuntimeOperation(domain, action, options, io) {
31174
31259
  const available = RUNTIME_OPERATIONS.filter((entry) => entry.domain === domain).map((entry) => entry.action);
31175
31260
  throw new Error(`Unknown ${domain} command "${action}". Available: ${available.join(', ')}`);
31176
31261
  }
31177
- const parsedParams = resolveRuntimeParams(operation.mcpName, options);
31178
- const command = resolveRuntimeOperationRequest(operation, parsedParams);
31262
+ const telemetry = startRuntimeOperationTelemetry(operation);
31263
+ try {
31264
+ return await runRuntimeOperation(operation, options, io, telemetry);
31265
+ }
31266
+ catch (error) {
31267
+ telemetry.fail(getRuntimeFailureReason(error));
31268
+ throw error;
31269
+ }
31270
+ }
31271
+ async function runRuntimeOperation(operation, options, io, telemetry) {
31272
+ let command;
31273
+ let timeoutMs;
31274
+ try {
31275
+ const parsedParams = resolveRuntimeParams(operation.mcpName, options);
31276
+ command = resolveRuntimeOperationRequest(operation, parsedParams);
31277
+ timeoutMs = parseIntegerOption(options.timeout, '--timeout', getDefaultRuntimeCommandTimeoutMs(operation.wsMethod));
31278
+ }
31279
+ catch (error) {
31280
+ telemetry.fail('invalid_input');
31281
+ throw error;
31282
+ }
31179
31283
  const workspaceRoot = await resolveWorkspaceRoot({
31180
31284
  cwd: io.cwd,
31181
31285
  workspace: typeof options.workspace === 'string' ? options.workspace : undefined,
@@ -31183,14 +31287,16 @@ async function handleRuntimeOperation(domain, action, options, io) {
31183
31287
  });
31184
31288
  const session = await getRuntimeSession(workspaceRoot);
31185
31289
  if (!session) {
31290
+ telemetry.fail('no_runtime');
31186
31291
  throw new Error(formatMissingRuntimeMessage(workspaceRoot));
31187
31292
  }
31293
+ telemetry.attachSession(session);
31188
31294
  const sendOptions = {
31189
31295
  port: session.port,
31190
31296
  method: operation.wsMethod,
31191
31297
  params: command.params,
31192
31298
  target: command.target,
31193
- timeoutMs: parseIntegerOption(options.timeout, '--timeout', getDefaultRuntimeCommandTimeoutMs(operation.wsMethod)),
31299
+ timeoutMs,
31194
31300
  runtimeSession: session,
31195
31301
  };
31196
31302
  let rawResult;
@@ -31198,12 +31304,14 @@ async function handleRuntimeOperation(domain, action, options, io) {
31198
31304
  rawResult = await sendRuntimeCommand(sendOptions);
31199
31305
  }
31200
31306
  catch (error) {
31307
+ telemetry.fail(getRuntimeFailureReason(error));
31201
31308
  if (operation.mcpName === 'xr_accept_session' &&
31202
31309
  error instanceof RuntimeCommandExecutionError) {
31203
31310
  error.message = `${error.message} Configure world.xr.offer as "once" or "always" before running iwsdk xr enter.`;
31204
31311
  }
31205
31312
  throw error;
31206
31313
  }
31314
+ telemetry.succeed();
31207
31315
  // Managed browser status would misdescribe a headset's session.
31208
31316
  let result = operation.mcpName === 'xr_get_session_status' &&
31209
31317
  command.target?.deviceClass !== 'physical'