@iwsdk/cli 0.5.3 → 1.0.0-rc.0

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.
Files changed (39) hide show
  1. package/README.md +62 -1
  2. package/bin/iwsdk.js +1 -1
  3. package/dist/browser-lease.d.ts +14 -0
  4. package/dist/browser-lease.d.ts.map +1 -0
  5. package/dist/cli-types.d.ts +1 -1
  6. package/dist/cli-types.d.ts.map +1 -1
  7. package/dist/cli.js +2811 -485
  8. package/dist/cli.js.map +1 -1
  9. package/dist/commands/browser.d.ts +14 -0
  10. package/dist/commands/browser.d.ts.map +1 -0
  11. package/dist/commands/dev.d.ts +6 -2
  12. package/dist/commands/dev.d.ts.map +1 -1
  13. package/dist/commands/runtime.d.ts.map +1 -1
  14. package/dist/commands/status.d.ts.map +1 -1
  15. package/dist/contract.js +481 -30
  16. package/dist/contract.js.map +1 -1
  17. package/dist/help.d.ts +1 -0
  18. package/dist/help.d.ts.map +1 -1
  19. package/dist/index.d.ts.map +1 -1
  20. package/dist/index.js +2813 -487
  21. package/dist/index.js.map +1 -1
  22. package/dist/mcp-stdio.d.ts.map +1 -1
  23. package/dist/runtime-contract.d.ts +70 -1
  24. package/dist/runtime-contract.d.ts.map +1 -1
  25. package/dist/runtime-files.d.ts +19 -0
  26. package/dist/runtime-files.d.ts.map +1 -0
  27. package/dist/runtime-files.js +318 -0
  28. package/dist/runtime-files.js.map +1 -0
  29. package/dist/runtime-owner.d.ts +50 -0
  30. package/dist/runtime-owner.d.ts.map +1 -0
  31. package/dist/runtime-owner.js +539 -0
  32. package/dist/runtime-owner.js.map +1 -0
  33. package/dist/runtime-state.d.ts +20 -18
  34. package/dist/runtime-state.d.ts.map +1 -1
  35. package/dist/runtime-transport.d.ts.map +1 -1
  36. package/dist/screenshot-output.d.ts +13 -0
  37. package/dist/screenshot-output.d.ts.map +1 -0
  38. package/guidance/AGENTS.md +96 -37
  39. package/package.json +16 -2
package/README.md CHANGED
@@ -14,7 +14,7 @@ It owns:
14
14
 
15
15
  ## Running without a local install
16
16
 
17
- Starter apps install this package and should run `npx iwsdk ...` from the app
17
+ Starter apps install this package and should run `npx @iwsdk/cli ...` from the app
18
18
  directory. Elsewhere, use the scoped package explicitly so npm does not resolve
19
19
  the unrelated `iwsdk` placeholder package:
20
20
 
@@ -40,3 +40,64 @@ action because it has no supported repository config for that choice.
40
40
  - `iwsdk adapter prune` removes managed MCP/permission entries and preserves
41
41
  editable instruction files.
42
42
  - `iwsdk adapter prompt` prints exact setup instructions for another harness.
43
+
44
+ ## Runtime ownership and targets
45
+
46
+ One canonical app workspace has one dev runtime and at most one managed browser.
47
+ This guarantee is within one OS/process namespace. Stop running dev processes
48
+ before upgrading the CLI and plugin together; concurrent old/new lock protocols
49
+ and shared workspaces across hosts, containers, or WSL are not supported.
50
+ `dev up` attaches to an existing runtime; `dev restart` explicitly stops it first.
51
+ A configured `server.port` (8081 in starters) is the runtime's address: if it is
52
+ occupied, startup fails instead of moving to another port. Without a configured
53
+ port, Vite may select the next available one. Browser failure does not stop HTTP serving
54
+ or HMR, including in foreground mode. `--no-open` disables managed-browser
55
+ launches for that session.
56
+ Managed browser profiles live in a private OS temporary directory outside the
57
+ served workspace. While that directory is retained, localStorage, IndexedDB, and
58
+ service workers survive browser recovery; normal OS temporary-file cleanup may
59
+ eventually remove them. A browser whose cleanup cannot be confirmed blocks
60
+ replacement and reports that condition.
61
+
62
+ Use `iwsdk runtime status` for the live lifecycle, `runtime targets` for connected
63
+ pages and their supported methods, and `runtime wait --input-json
64
+ '{"afterRevision":7,"timeoutMs":25000}'` to wait without causing recovery.
65
+ `runtime recover` explicitly retries a failed launch. The MCP equivalents are
66
+ `runtime_get_status`, `runtime_list_targets`, `runtime_wait`, and `runtime_recover`.
67
+ `dev status` remains a read of the persisted discovery snapshot. `dev up`
68
+ reports `browserCommandReady` and can return while a lifecycle-managed browser
69
+ is still launching; follow its `browserNextAction` or wait until readiness is
70
+ true before issuing browser-backed commands.
71
+
72
+ Commands default to the managed browser. Recovery returns `browser_relaunched`
73
+ and `outcome: "not_executed"`; inspect the new state and issue a fresh command.
74
+ A disconnection after dispatch returns `outcome_unknown`: a mutation might have
75
+ executed, so inspect state before retrying. No command is automatically replayed.
76
+
77
+ To control a Quest, run `runtime pair-headset --input-json
78
+ '{"headsetId":"ADB_SERIAL"}'`, set up `adb -s ADB_SERIAL reverse tcp:PORT tcp:PORT`,
79
+ and open the returned URL on that exact device. Pairings last for the dev session.
80
+ `runtime targets` returns an exact `runtimeTarget` to copy into tool arguments:
81
+
82
+ ```json
83
+ {
84
+ "runtimeTarget": {
85
+ "deviceClass": "physical",
86
+ "headsetId": "ADB_SERIAL",
87
+ "pageId": "page-from-discovery",
88
+ "tabGeneration": 2
89
+ }
90
+ }
91
+ ```
92
+
93
+ Physical pages are never selected implicitly. Reload runs through the app bridge;
94
+ screenshot, snapshot, interaction, profiling, console capture, and the managed
95
+ editor remain host-only and return `unsupported_on_target` for physical pages.
96
+ Runtime/ECS methods require that page's framework to be ready. Native pose control
97
+ still requires the explicit native-XR option. No console listeners are added to
98
+ the headset app. A page reload advances its generation; rediscover before another
99
+ command. `runtimeTarget` is distinct from existing tools' position-vector `target`.
100
+
101
+ `browser run` holds the managed command lease for its complete CDP session. Do not
102
+ call another managed-browser tool from inside a leased script. A lost runner lease
103
+ retires the browser, preventing unfinished CDP work from overlapping later commands.
package/bin/iwsdk.js CHANGED
@@ -12,7 +12,7 @@ import { fileURLToPath } from 'url';
12
12
  const entrypoint = new URL('../dist/cli.js', import.meta.url);
13
13
  if (!existsSync(fileURLToPath(entrypoint))) {
14
14
  console.error(
15
- 'The local @iwsdk/cli package has not been built. Run "corepack pnpm@10.18.3 --filter @iwsdk/cli build" from the immersive-web-sdk repository, then retry.',
15
+ 'The local @iwsdk/cli package has not been built. Run "pnpm --filter @iwsdk/cli build" from the immersive-web-sdk repository, then retry.',
16
16
  );
17
17
  process.exitCode = 1;
18
18
  } else {
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
3
+ *
4
+ * This source code is licensed under the MIT license found in the
5
+ * LICENSE file in the root directory of this source tree.
6
+ */
7
+ import type { RuntimeSession } from './runtime-contract.js';
8
+ /** Keep a command connection open for the complete secondary-CDP operation. */
9
+ export declare function acquireBrowserLease(session: RuntimeSession, timeoutMs: number): Promise<{
10
+ release(): void;
11
+ abandon(): void;
12
+ lost: Promise<never>;
13
+ }>;
14
+ //# sourceMappingURL=browser-lease.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"browser-lease.d.ts","sourceRoot":"","sources":["../src/browser-lease.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,+EAA+E;AAC/E,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;IACT,OAAO,IAAI,IAAI,CAAC;IAChB,OAAO,IAAI,IAAI,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;CACtB,CAAC,CAiGD"}
@@ -22,7 +22,7 @@ export type CliFailure = {
22
22
  details?: unknown;
23
23
  };
24
24
  };
25
- export type CliCommandResult = CliSuccess<unknown> | CliFailure | CliRawOutput | null | undefined;
25
+ export type CliCommandResult = CliSuccess<unknown> | CliFailure | CliRawOutput | number | null | undefined;
26
26
  export interface ParsedArgv {
27
27
  positionals: string[];
28
28
  options: CliOptions;
@@ -1 +1 @@
1
- {"version":3,"file":"cli-types.d.ts","sourceRoot":"","sources":["../src/cli-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,OAAO,CAAC;AAC9C,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AAExD,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,OAAO,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,CAAC;AAC5D,MAAM,MAAM,YAAY,GAAG;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAC3D,MAAM,MAAM,UAAU,GAAG;IACvB,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,gBAAgB,GACxB,UAAU,CAAC,OAAO,CAAC,GACnB,UAAU,GACV,YAAY,GACZ,IAAI,GACJ,SAAS,CAAC;AAEd,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,UAAU,CAAC;CACrB;AAED,MAAM,WAAW,KAAK;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IAC9B,GAAG,EAAE,MAAM,CAAC;CACb"}
1
+ {"version":3,"file":"cli-types.d.ts","sourceRoot":"","sources":["../src/cli-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,OAAO,CAAC;AAC9C,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;AAExD,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,OAAO,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,CAAC;AAC5D,MAAM,MAAM,YAAY,GAAG;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAC3D,MAAM,MAAM,UAAU,GAAG;IACvB,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,gBAAgB,GACxB,UAAU,CAAC,OAAO,CAAC,GACnB,UAAU,GACV,YAAY,GACZ,MAAM,GACN,IAAI,GACJ,SAAS,CAAC;AAEd,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,UAAU,CAAC;CACrB;AAED,MAAM,WAAW,KAAK;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IAC9B,GAAG,EAAE,MAAM,CAAC;CACb"}