@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.
- package/README.md +62 -1
- package/bin/iwsdk.js +1 -1
- package/dist/browser-lease.d.ts +14 -0
- package/dist/browser-lease.d.ts.map +1 -0
- package/dist/cli-types.d.ts +1 -1
- package/dist/cli-types.d.ts.map +1 -1
- package/dist/cli.js +2811 -485
- package/dist/cli.js.map +1 -1
- package/dist/commands/browser.d.ts +14 -0
- package/dist/commands/browser.d.ts.map +1 -0
- package/dist/commands/dev.d.ts +6 -2
- package/dist/commands/dev.d.ts.map +1 -1
- package/dist/commands/runtime.d.ts.map +1 -1
- package/dist/commands/status.d.ts.map +1 -1
- package/dist/contract.js +481 -30
- package/dist/contract.js.map +1 -1
- package/dist/help.d.ts +1 -0
- package/dist/help.d.ts.map +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2813 -487
- package/dist/index.js.map +1 -1
- package/dist/mcp-stdio.d.ts.map +1 -1
- package/dist/runtime-contract.d.ts +70 -1
- package/dist/runtime-contract.d.ts.map +1 -1
- package/dist/runtime-files.d.ts +19 -0
- package/dist/runtime-files.d.ts.map +1 -0
- package/dist/runtime-files.js +318 -0
- package/dist/runtime-files.js.map +1 -0
- package/dist/runtime-owner.d.ts +50 -0
- package/dist/runtime-owner.d.ts.map +1 -0
- package/dist/runtime-owner.js +539 -0
- package/dist/runtime-owner.js.map +1 -0
- package/dist/runtime-state.d.ts +20 -18
- package/dist/runtime-state.d.ts.map +1 -1
- package/dist/runtime-transport.d.ts.map +1 -1
- package/dist/screenshot-output.d.ts +13 -0
- package/dist/screenshot-output.d.ts.map +1 -0
- package/guidance/AGENTS.md +96 -37
- 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 "
|
|
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"}
|
package/dist/cli-types.d.ts
CHANGED
|
@@ -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;
|
package/dist/cli-types.d.ts.map
CHANGED
|
@@ -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"}
|