@revoengine/cli 1.0.29 → 1.0.31

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 (69) hide show
  1. package/README.md +156 -3
  2. package/dist/src/automation-contract.generated.d.ts +742 -0
  3. package/dist/src/automation-contract.generated.js +1021 -0
  4. package/dist/src/cli.js +9 -1
  5. package/dist/src/client.d.ts +24 -0
  6. package/dist/src/client.js +60 -0
  7. package/dist/src/commands/component.js +56 -23
  8. package/dist/src/commands/env.js +1 -1
  9. package/dist/src/commands/index.d.ts +2 -0
  10. package/dist/src/commands/index.js +2 -0
  11. package/dist/src/commands/studio.d.ts +3 -0
  12. package/dist/src/commands/studio.js +114 -0
  13. package/dist/src/commands/terminal-browser-human-input.d.ts +11 -0
  14. package/dist/src/commands/terminal-browser-human-input.js +44 -0
  15. package/dist/src/commands/terminal-browser-interaction.d.ts +25 -0
  16. package/dist/src/commands/terminal-browser-interaction.js +56 -0
  17. package/dist/src/commands/terminal-browser-live-protocol.d.ts +151 -0
  18. package/dist/src/commands/terminal-browser-live-protocol.js +177 -0
  19. package/dist/src/commands/terminal-browser-live-transport.d.ts +41 -0
  20. package/dist/src/commands/terminal-browser-live-transport.js +206 -0
  21. package/dist/src/commands/terminal-browser-live.d.ts +114 -0
  22. package/dist/src/commands/terminal-browser-live.js +455 -0
  23. package/dist/src/commands/terminal-browser-observation.d.ts +10 -0
  24. package/dist/src/commands/terminal-browser-observation.js +27 -0
  25. package/dist/src/commands/terminal-browser-page-input.d.ts +8 -0
  26. package/dist/src/commands/terminal-browser-page-input.js +94 -0
  27. package/dist/src/commands/terminal-browser-profile-preferences.d.ts +37 -0
  28. package/dist/src/commands/terminal-browser-profile-preferences.js +136 -0
  29. package/dist/src/commands/terminal-browser-profile.d.ts +52 -0
  30. package/dist/src/commands/terminal-browser-profile.js +447 -0
  31. package/dist/src/commands/terminal-browser.d.ts +28 -1
  32. package/dist/src/commands/terminal-browser.js +401 -55
  33. package/dist/src/commands/terminal-policy.js +2 -0
  34. package/dist/src/commands/terminal-public-web-proxy.d.ts +14 -0
  35. package/dist/src/commands/terminal-public-web-proxy.js +141 -0
  36. package/dist/src/commands/terminal-public-web.d.ts +11 -0
  37. package/dist/src/commands/terminal-public-web.js +99 -0
  38. package/dist/src/commands/terminal.d.ts +1 -0
  39. package/dist/src/commands/terminal.js +92 -9
  40. package/dist/src/commands/tests.d.ts +3 -0
  41. package/dist/src/commands/tests.js +236 -0
  42. package/dist/src/component-element-validation.d.ts +8 -0
  43. package/dist/src/component-element-validation.js +79 -0
  44. package/dist/src/component-lifecycle.d.ts +3 -0
  45. package/dist/src/component-lifecycle.js +17 -0
  46. package/dist/src/component-lock.d.ts +17 -12
  47. package/dist/src/component-lock.js +57 -6
  48. package/dist/src/component-manifests.js +3 -0
  49. package/dist/src/component-source-validation.d.ts +5 -0
  50. package/dist/src/component-source-validation.js +27 -0
  51. package/dist/src/env-sync.js +67 -9
  52. package/dist/src/native-tests.d.ts +61 -0
  53. package/dist/src/native-tests.js +20 -0
  54. package/dist/src/request-contract.d.ts +39 -0
  55. package/dist/src/request-contract.js +138 -0
  56. package/dist/src/resource-syncs/agent-sync.js +47 -7
  57. package/dist/src/resource-syncs/database-table-sync.js +8 -8
  58. package/dist/src/resource-syncs/endpoint-sync.js +20 -14
  59. package/dist/src/resource-syncs/group-sync.js +8 -3
  60. package/dist/src/resource-syncs/job-template-sync.js +75 -28
  61. package/dist/src/resource-syncs/role-group-sync.js +8 -0
  62. package/dist/src/resource-syncs/runtime-definition-validation.d.ts +14 -0
  63. package/dist/src/resource-syncs/runtime-definition-validation.js +153 -0
  64. package/dist/src/test-workspace.d.ts +33 -0
  65. package/dist/src/test-workspace.js +156 -0
  66. package/dist/src/types.d.ts +1 -0
  67. package/dist/src/ui.js +12 -0
  68. package/dist/src/update-notifier.d.ts +1 -1
  69. package/package.json +5 -3
package/README.md CHANGED
@@ -10,7 +10,13 @@ The CLI has three main capabilities:
10
10
  2. **Project migration** — plan, run, and verify a direct migration between two saved projects with `--from` and `--to`.
11
11
  3. **Resource synchronization** — work with one supported resource family through its dedicated `pull`, `plan`, and `push` commands.
12
12
 
13
- ## Version 1.0.18
13
+ ## Version 1.0.30
14
+
15
+ This release includes the complete CLI Studio session and native test commands, terminal Browser profiles, Live Preview, recording and public-page rendering, together with definition contract fixes. Studio sessions/native tests require a backend with the Studio APIs; Live Preview and recording require matching Realtime/API/Gateway and frontend support. Updating the CLI alone does not enable these server features. Existing runner registration and older terminal/browser operations remain compatible with backends that filter unsupported capabilities.
16
+
17
+ Runtime packages include all compiled modules, including native test workspace capture, Browser helpers and subprocess workers. Named authentication profiles require a foreground macOS runner and the host Keychain. Live profile choices are bounded to 32 entries while the complete encrypted catalog remains available for profile management.
18
+
19
+ ## Repository reconciliation
14
20
 
15
21
  Repository `plan/deploy --prune` now releases occupied Job Template names before upserts by deleting the reviewed obsolete templates and their obsolete Event/Schedule consumers. Retained references block this early phase; remaining deletions follow verified upserts. Saved plans include deletion timing, so regenerate older replacement plans before deployment. See the repository workflow below for approval, scope and failure behavior.
16
22
 
@@ -108,11 +114,29 @@ On macOS, workspace commands may use Unix-domain sockets only inside their own p
108
114
 
109
115
  The terminal approval UI supports Allow once, Allow for 15 minutes, Allow for 1 hour, Allow for 8 hours, Allow for 24 hours and Allow for this thread. Whole-thread access requires this runner's `terminal_thread_scope_v1` capability. It covers only the requested Commands and Network levels, survives later messages and short reconnects, and carries no hourly deadline. Disconnect, thread deletion and a device grant revision change revoke it. Realtime rechecks the consent on heartbeat, including idle Browser contexts; scope revocation closes only the affected context. Process `background` mode and the one-hour Browser idle retention are independent of this approval duration.
110
116
 
111
- The runner keeps a separate browser context for each connected assistant chat, so navigation, DOM inspection, clicks, form controls, waiting, scrolling, and screenshots share that chat's cookies and page state. Completed actions return a stable browserSessionId, activeTabId and tab inventory (ID, title, sanitized URL and active flag), plus sessionCreated. Use tabs, new_tab with a URL, select_tab or close_tab with tabId, and close to manage the session. Other actions accept tabId. Selecting a tab brings it to the foreground without navigation; popup tabs receive IDs and return to their opener when closed. Tab-aware operations require browser_tabs_v1 in Realtime and Gateway. Browser sessions expire after one hour idle (up to four per runner and sixteen tabs per session), on a Local or Full network lease expiry, or when the runner stops or its access is revoked. A one-time Browser network approval closes its context immediately after that action finishes. DOM results include bounded selector hints for interactive elements without their field values. The Browser action supports `fill`, `check`, `select`, `press`, `scroll`, and `wait_for` as well as navigation, DOM, and click. Ordinary `fill` rejects password and secret-like controls; the Assistant may request a one-time secure credential dialog, which encrypts the value to this runner and fills it in memory without sending it in model tool arguments. The tab-aware handoff authenticates its target tab ID and rejects a switched page even on the same origin. Screenshots can capture the viewport (default), the full page, one selected element, or a bounded viewport crop. For viewport capture, an optional selector limits only the returned DOM text; the image still covers the viewport. Element capture requires a selector. Full-page and crop capture reject selectors. A screenshot is uploaded and attached automatically; calling `save_image` on its local path uploads a second copy. For custom Playwright E2E scripts, run them as ordinary terminal commands in the project, using the requested sandbox and network grant; the Browser action does not execute arbitrary JavaScript.
117
+ DOM control summaries prioritize the visible focused control and its containing dialog, followed by other visible dialog/alertdialog controls and ordinary page controls. Hidden controls are excluded before the 120-control cap; ordering stays stable without duplicates, field values stay omitted, and the inventory remains bounded to 12,000 characters.
118
+
119
+ The runner keeps a separate browser context for each connected assistant chat, so navigation, DOM inspection, clicks, form controls, waiting, scrolling, and screenshots share that chat's cookies and page state. Completed actions return a stable browserSessionId, activeTabId and tab inventory (ID, title, sanitized URL and active flag), plus sessionCreated. Use tabs, new_tab with a URL, select_tab or close_tab with tabId, and close to manage the session. Other actions accept tabId. Selecting a tab brings it to the foreground without navigation; popup tabs receive IDs and return to their opener when closed. Tab-aware operations require browser_tabs_v1 in Realtime and Gateway. Browser sessions expire after one hour idle (up to four per runner and sixteen tabs per session), on a Local or Full network lease expiry, or when the runner stops or its access is revoked. A one-time Browser network approval closes its context immediately after that action finishes. DOM results include bounded selector hints for interactive elements without their field values. The Browser action supports `fill`, `check`, `select`, `press`, `scroll`, and `wait_for` as well as navigation, DOM, and click. Ordinary `fill` rejects password and secret-like controls; the Assistant may request a one-time secure credential dialog, which encrypts the value to this runner and fills it in memory without sending it in model tool arguments. The tab-aware handoff authenticates its target tab ID and rejects a switched page even on the same origin. Screenshots can capture the viewport (default), the full page, one selected element, or a bounded viewport crop. Crop coordinates remain relative to the visible viewport after scrolling. For viewport capture, an optional selector limits only the returned DOM text; the image still covers the viewport. Element capture requires a selector. Full-page and crop capture reject selectors. A screenshot is uploaded and attached automatically; calling `save_image` on its local path uploads a second copy. For custom Playwright E2E scripts, run them as ordinary terminal commands in the project, using the requested sandbox and network grant; the Browser action does not execute arbitrary JavaScript.
112
120
 
113
121
 
114
122
  The Browser bridge advertises `browser_timeout_v1`. Agent calls can set `action_timeout_ms` between 1 and 120000 ms for Playwright navigation, interactions, DOM reads and capture. Omitted values retain navigation 30 s, interaction/DOM 10 s and capture 20 s defaults. Selector waits accept `wait_timeout_ms` up to 120000 ms and are capped by the operation timeout when both are supplied. These budgets never extend access expiry or retry an interaction. At a capacity limit the agent can list and close a selected tab, or close its own chat Browser session; closing a session discards its cookies.
115
123
 
124
+ ### Public page reads
125
+
126
+ Assistant `web_load` uses HTTP first. An eligible failed or JavaScript-only page
127
+ can fall back to this runner's `browser_public_read_v1` capability when the selected
128
+ online terminal already has Full network access. The fallback asks for no new grant.
129
+ It uses a separate empty browser context and never restores a login profile or
130
+ changes the chat's open tabs, cookies, form state or Live Preview ownership.
131
+ Up to three public reads run concurrently, each with an eight-second total budget.
132
+ Every request uses a proxy that pins validated public DNS addresses, blocking LAN,
133
+ loopback and metadata destinations, including redirects and page resources. Only
134
+ GET/HEAD requests are allowed; downloads, WebSockets and worker transports are
135
+ disabled. Transport is capped at eight MiB per read. Temporary Chromium processes
136
+ and proxies close on success, failure, cancellation or expiry. CAPTCHA, login and
137
+ pages requiring blocked transports can still fail. Older runners keep HTTP-only
138
+ web loading until upgraded and reconnected.
139
+
116
140
  ### Device workspaces and direct transfer
117
141
 
118
142
  The saved `agentTerminalId` identifies the device across terminal restarts. `deviceId` is an alias. Connecting another directory with the same profile and terminal name reuses the saved device secret and registers a pending workspace under that device. Approve its access in AI Agents → Terminals → Workspaces. A running device refreshes its contract; it does not need a second runner. Ambiguous older duplicate registrations require `--terminal-id`. Services remain pinned to the device UUID and original service directory.
@@ -121,6 +145,29 @@ Current runners advertise `terminal_workspaces_v1`, `browser_control_v1`, `file_
121
145
 
122
146
  Browser inventory exposes its owning chat and workspace. The model can explicitly close permitted same-actor sessions/tabs to free the four-session/sixteen-tab capacity; active sessions are never silently evicted. Inventory/cleanup preserves the existing network lease. Local/full scope changes recreate the browser context and require browser workflow recovery.
123
147
 
148
+ #### Remember browser authentication on macOS
149
+
150
+ Browser state is ephemeral by default. A foreground runner can explicitly opt in to a named authentication profile:
151
+
152
+ ```bash
153
+ revo terminal connect --workspace "$HOME/projects/my-project" --name "Work Mac" --browser-profile "AP work"
154
+ revo terminal browser-profile forget --workspace "$HOME/projects/my-project" --terminal-id <terminal-uuid> --browser-profile "AP work"
155
+ ```
156
+
157
+ The selected profile reuses cookies, local storage and IndexedDB (including Firebase Authentication state) across browser context closure and foreground runner restarts. The CLI flag selects a profile for that invocation. In Live Preview, selecting a profile and choosing it as the default saves the selection in an encrypted, scoped catalog; later chats and foreground restarts restore that default without repeating the flag. Stop an already connected runner before selecting a profile. macOS Keychain holds the encryption key; AES-256-GCM snapshots under the CLI configuration's `browser-profiles/` directory are private and written atomically. Locked or unavailable Keychain access fails closed. Live profile operations use asynchronous Keychain subprocesses so access-expiry timers remain active while the operating system responds. No plaintext key file, environment-key fallback or personal Chrome profile is used. This option currently rejects Linux, Windows and background service runners; passing it to service installation also fails rather than losing the selection.
158
+
159
+ A profile belongs to one API URL, instance, actor, terminal and canonical workspace. The same name in another scope is a separate profile. Each chat still gets its own live context. Only one live context can hold a named profile's writer lease at a time; a concurrent chat receives `browser_profile_busy` and must wait for the first context to close or use another profile. This prevents one chat silently replacing another chat's authentication changes. A dead runner's writer lease can be recovered on the next open.
160
+
161
+ State is checkpointed after browser actions and on explicit browser close. The CLI never copies secure-input values from the bridge or password-field DOM into a profile. Snapshots capture site-owned cookies, local storage and IndexedDB, which can contain authentication tokens and other sensitive values; all of that state is encrypted. A checkpoint does not certify that login succeeded. Network lease expiry, revocation and runner shutdown close Chromium without waiting for a new checkpoint; the last committed encrypted snapshot remains available for a later authorized invocation. No profile extends network grants, restores running tabs or guarantees the identity provider's session lifetime. Websites can expire tokens, require MFA or require a new interactive login. Local/full scope changes still recreate the runtime context and reinstall network guards before restoring approved state.
162
+
163
+ Live Preview uses a separate authenticated outbound Realtime WebSocket. It streams the active tab and SSO popups as JPEG frames at up to five frames per second, with CSS viewport and image geometry; it opens no local server or CDP port. During human takeover, static pages receive a genuine viewport refresh every two seconds so the latest displayed frame remains usable after reading; observation expiry and authorization checks remain enforced. Read-only preview can be closed while the model continues. Takeover pauses all model browser actions for the entire chat browser session. Human input is encrypted to the current runner connection, scoped to the actor, chat, workspace, session, control epoch and fresh observation, and is never replayed after a disconnect. Private takeover is the default. Release clears secret-like inputs, checkpoints the opted-in profile and returns a fresh observation before the model resumes. A disconnect during takeover leaves the browser blocked until explicit reconnection and release. Connected takeover prevents idle cleanup but never extends network permission expiry.
164
+
165
+ Coordinates require a recent observation of the active tab. Navigation, tab changes, resize, scrolling and interaction invalidate previous geometry; media frames alone do not invalidate the model's recent screenshot. Model text/key input rejects a focused secret control and must use the secure credential flow. Profile selection creates a new named profile from the current authenticated state; selecting an existing profile restores it. Making the current profile the default preserves current authentication. Reset explicitly clears the selected profile. Profiles remain isolated by actor, API URL, instance, device and workspace; a busy profile returns a safe error before changing the active browser.
166
+
167
+ Recording is optional and off by default. It can be enabled in read-only preview to capture model work; private human/authentication phases reject a new recording, and Stop remains available. Explicit public/demo recording uses Playwright's native WebM segments and can continue while the model works after release. Private takeover and secret-focused input stop the active recording before typing; resuming public work starts another segment. Input text and action labels are not added to video or runner logs. Local recordings are stored in private directories with private file permissions; Storage or Both additionally requires current Full network access and a separately authorized upload descriptor. Recordings and browser grants have separate lifetimes. Encrypted profiles are currently available only to foreground macOS runners; unsupported hosts and background service profiles fail closed.
168
+
169
+ `forget` requires the profile's workspace and selected terminal, authenticates the actor with the current API profile, and deletes its snapshot and Keychain key. It rejects a profile currently in use; close that chat's browser or stop its runner first. Forgetting local state does not revoke the website's server-side sessions. An ordinary browser close or terminal disconnect retains the opted-in snapshot; revoked grants cannot open a new browser until access is approved again. Use `forget` when the stored login should be removed.
170
+
124
171
  `upload_file` and `download_file` stream an explicit authorized workspace file directly to/from GCS HTTPS signed/resumable URLs with permitted headers. Full network permission is required. WebSocket carries metadata only. Resumable uploads report committed offsets and partial completion; do not finalize a Storage upload before completion or blindly repeat an uncertain upload. Downloads commit atomically and do not overwrite unless explicitly requested. The stream's idle timeout is 90 seconds; grant expiry and runner lifetime still apply. Signed URLs/headers are credentials and must not be copied into logs or source files.
125
172
 
126
173
  Interactive PTY commands use the optional native `node-pty` package. An unavailable native build does not block CLI installation; PTY requests return `pty_unavailable` until the optional package can be installed. To skip native installation when PTY is not needed, install locally with `npm install --omit=optional @revoengine/cli` and run `npx revo`; npm 11.9 may still install the optional dependency during a global installation. On macOS, the runner verifies the spawn helper's executable permission when a PTY starts. Ordinary commands and local development servers run with pipes.
@@ -214,6 +261,8 @@ Subsequent resource synchronization creates `.revoengine/revo.lock.json` baselin
214
261
 
215
262
  Use `revo project update` to refresh an existing project. When the RevoEngine workspace is nested, pass its path, for example `revo project init ./backend`.
216
263
 
264
+ Migrated JS/TS libraries contain a permanent `@default` element and explicit named exports. Its source remains editable. Plan and push reject omitting an existing target default, including forced pushes and environment migration; refresh the library from the target and reconcile local changes before deployment. The CLI preserves the target default element ID when saving source.
265
+
217
266
  Stable Keys are the durable identity used across instances. UUIDs and versions remain instance-local and are not used to match portable resources. Before the first migration, inspect and apply missing keys on the source:
218
267
 
219
268
  ```bash
@@ -428,6 +477,16 @@ Previously pulled Event manifests with `extensions.input` and `extensions.inputM
428
477
 
429
478
  Omitted fields mean `input: {}` and `inputMode: "override"` in the CLI's desired definition, including updates. Older Schedule pulls did not export these fields: re-pull from the source before promotion if that source uses nondefault automation input. A plan shows any difference from the target; approving an overwrite applies the manifest defaults. Regenerate saved reviewed plans after updating the CLI because input and mode now participate in definition hashes.
430
479
 
480
+ ### Definition contract checks
481
+
482
+ Endpoint and Job Template plans validate supported request fields, option types, numeric bounds, execution policy, retry backoff and static guard rules against a checked-in projection of the canonical Platform OpenAPI and DTO validators. The package runs independently of the backend checkout. Maintainers use `npm run generate:automation-contract` to regenerate it and `npm run check:automation-contract` to verify it against a sibling `@revoengine-platform` checkout. When Studio contracts live on a separate backend branch, supply its source root with `--studio-platform-root=/path/to/platform-with-studio` or `REVO_STUDIO_PLATFORM_SOURCE_ROOT`; the generator derives only those additions from that canonical source and rejects conflicting shared request fields. Source-alignment tests detect DTO and relevant runtime-policy changes. Sandbox source/schema compilation, instance quotas, permission checks and live resource availability remain API responsibilities.
483
+
484
+ Portable hashes treat proven backend defaults as equivalent, including normalized Endpoint paths and Job timeout, concurrency and retry defaults. Exact historical Endpoint/Job hashes remain valid only when they match the complete live definition. Regenerate saved reviewed plans after upgrading; re-pull definitions when an older baseline cannot be proven. When Job creation materializes a memory value absent from the desired definition, the CLI restores the desired options through a version-guarded update before readback verification.
485
+
486
+ Component configuration updates send only mutable DTO fields. Activation uses the dedicated activate/disable routes with a review token tied to the observed version; enabling follows source readback verification. Component type changes are blocked. Raw element fields, keys, orders, paths and source size are checked before writes; complete CLI deployments require explicit nonempty elements because an empty create request generates backend starter content. `async` controls creation transport and does not represent persisted Component state.
487
+
488
+ Database column metadata preserves business JSON, including nested `id`, `version`, `users` and `tags` fields. Agent Plugin input/output schemas preserve property names, examples and defaults without configuration rewriting. Tagged Vault bindings remain target-local and cannot be transferred as static input. Group and Role Group manifests reject unsupported fields before writing; user metadata accepts at most 64 top-level keys and 16 KiB of UTF-8 JSON, reserves top-level `__*` keys, and preserves unrestricted nested JSON keys.
489
+
431
490
  ### Work with one resource family
432
491
 
433
492
  Every resource family has a dedicated synchronization flow. With a stored login or `REVO_URL` and `REVO_TOKEN`, omit `--project` to use the active connection:
@@ -653,7 +712,7 @@ Repository `plan/deploy` without `--activate` preserves existing Event and Sched
653
712
 
654
713
  `CUSTOM_NODEJS` deployment verifies runtime availability and the active desired revision after source readback. Automatic deployment waits up to two minutes for readiness; failed attempts, manual activation requirements and unavailable/pending revisions fail verification without adopting a deployment baseline. Re-run after the runtime is ready. Named `env diff/apply` also reports unavailable unchanged custom runtimes and returns an error on unverified writes. Definition synchronization does not invoke provider/plugin tests; component dependencies and their pinned revisions are checked with read-only API calls, including unchanged definitions.
655
714
 
656
- Execution options are compared without hiding runtime differences: missing Job Template memory means 256 MB; explicit 128 MB remains distinct. An empty `options.input` overrides legacy `inputs`. Endpoint `memory: null` remains distinct from 32 MB. If the backend substitutes a different value, readback verification fails rather than recording false convergence.
715
+ Execution options are compared without hiding runtime differences: an explicit Job Template memory value remains distinct from missing/null memory, which falls back to template input or the current 128 MiB runtime default. The create API initially materializes 256 MiB; CLI creation restores the desired options with a version-guarded update before verification when needed. An empty `options.input` overrides legacy `inputs`. Endpoint null/zero memory is normalized to 32 MiB by both create and update. Old Job baselines that omitted explicit 256 MiB cannot prove memory convergence; re-pull and review those definitions before promotion.
657
716
 
658
717
  ## Deployment digests and local lock updates
659
718
 
@@ -679,3 +738,97 @@ cache. Pruning still checks retained and out-of-scope consumers. Human output re
679
738
  phase start/end/duration and a heartbeat for slow phases; JSON output remains clean.
680
739
  Stable Keys match identity across instances. Current versions and mutation-review
681
740
  tokens remain necessary to reject changes made after plan approval.
741
+
742
+ ### Native tests from a worktree or stored Components
743
+
744
+ `CODE_JS_TEST` and `CODE_TS_TEST` are ordinary Component source types. A native test Component is a suite: its code registers named cases with `test.case`, and `testConfig.targets` names the Components it exercises. The same suite can run in Studio, against stored Components, or against unpublished source from a local worktree.
745
+
746
+ ```bash
747
+ # Discover suites from the configured local workspace, without an API call.
748
+ revo tests list --json
749
+ revo tests list --workspace ./checkout-worktree --search Checkout
750
+
751
+ # Upload a captured source overlay to the host fixture runner; no source is published.
752
+ revo tests run "Checkout tests"
753
+ revo tests run "Checkout tests" "Delivery tests" --timeout 30 --json
754
+ revo tests run --all --json
755
+
756
+ # Discover and execute stored suites without opening or creating a Studio session.
757
+ revo tests list --remote --search Checkout --json
758
+ revo tests run "Checkout tests" --remote --json
759
+
760
+ # Persist a run now; explicitly continue execution later.
761
+ revo tests run "Checkout tests" --no-wait --operation-id <uuid> --json
762
+ revo tests resume <runId> --json
763
+ revo tests cancel <runId> --json
764
+ ```
765
+
766
+ Local discovery reads `Components/**/component.json` below the project-configured workspace, or the current directory if there is no project configuration. `elements/<order>_<key>.<extension>` and the existing `details/` layout supply the current source. Test targets and uploaded Components use their exact names; instance IDs, element IDs, local source versions and reserved metadata are not used as cross-instance execution authority. Source symlinks that escape the selected workspace are rejected. Local execution uploads a bounded snapshot of the worktree's code Components, test code and fixtures; the host resolves dependencies against that overlay and its captured stored source. It does not run the code in the CLI's Node process.
767
+
768
+ For example, a pulled test's `component.json` can contain:
769
+
770
+ ```json
771
+ {
772
+ "name": "Checkout tests",
773
+ "type": "CODE_TS_TEST",
774
+ "active": true,
775
+ "testConfig": {
776
+ "mode": "fixture",
777
+ "targets": ["Checkout"],
778
+ "fixtures": { "order": { "quantity": 2, "unitPrice": 21 } }
779
+ },
780
+ "elements": [{ "key": "Test", "order": 0, "details": "" }]
781
+ }
782
+ ```
783
+
784
+ Its `elements/0_Test.ts` registers the cases and awaits host-owned assertions:
785
+
786
+ ```typescript
787
+ await test.case('two items total 42', async () => {
788
+ const input = await test.fixture<{ quantity: number; unitPrice: number }>('order');
789
+ const output = await test.runComponent<{ results: { Main: { total: number } } }>('Checkout', input);
790
+ await test.assertEqual(output.results.Main.total, 42);
791
+ });
792
+ ```
793
+
794
+ The runner exposes `test.*` only during native execution. Fixture effects are intercepted by the host and require configured fixtures; `readOnly` alone is not isolation. Integration suites need the reviewed Studio lifecycle and cannot be run as standalone fixtures. `--all` selects fixture suites; selecting an integration suite explicitly produces a clear error. One captured run supports up to 20 named suites, with a per-suite timeout from 1 to 60 seconds. Larger selections are automatically split into sequential batches; one batch is completed before the next is captured. The local source overlay is read once for the collection, and each run records its own pinned snapshot digest.
795
+
796
+ Runs and results are durable. The API admits the authenticated request and forwards captured execution to Sandbox; the CLI claims one queued suite at a time and collects its recorded cases, assertions and result. `--no-wait` only creates runs: a later `tests resume` drives execution, rather than starting a detached background job. Reusing `--operation-id` retries the exact submitted snapshot. The first batch uses that identity and subsequent batches derive stable identities from it and their position. A changed batch payload with its ID is rejected by the host. Collections are bounded to 100 sequential batches, or 10 batches with `--no-wait`; existing pending runs can reduce the host's remaining admission capacity. If admission stops, the response retains all already captured run IDs for resume or cancellation.
797
+
798
+ The default collection wait budget is 600 seconds, configurable up to 3600 with `--wait-timeout`. An interrupted connection or expired wait leaves captured runs available for `tests resume`; it does not report success or publish code. A single run's JSON output is the unchanged host envelope, including `runId`, `snapshotDigest`, suite status, cases, assertions and errors. Multiple runs return `{ "status": "PASSED", "runIds": [...], "executions": [...] }`, with complete host envelopes in `executions`. Completed unsuccessful runs exit with status 1. A successful result requires every suite to pass with real cases and successful assertions; an empty or incomplete result cannot make CI green. An intentionally queued `--no-wait` submission exits successfully without claiming that tests passed.
799
+
800
+ Run fixture suites before a deployment job, using the same worktree:
801
+
802
+ ```bash
803
+ revo tests run --all --json > native-test-results.json
804
+ # Only proceed to the explicit Studio review/commit/activation flow after exit 0.
805
+ ```
806
+
807
+ ### Shared Studio sessions
808
+
809
+ Component source writes enter Studio through the existing API adapters. A legacy `component push`, environment migration or raw source write stages a short session and returns `STUDIO_REVIEW_REQUIRED` with the session and candidate to review. It does not report a successful source commit, approve a waiver or fall back to sequential writes. Review, commit, runtime preparation and activation remain explicit steps.
810
+
811
+ `revo studio promote --body-file session.json --json` stages a complete multi-component draft and prints its session ID and working diff. The JSON uses the Platform API Studio create contract: `title`, `intent`, and `resources` with each full `proposed` component. Every existing component requires its locally observed `componentId` and `baseVersion`; promotion does not refresh that base from the server. New components omit `componentId` and the server assigns their stable session resource IDs.
812
+
813
+ ```bash
814
+ revo studio list --json
815
+ revo studio promote --body-file session.json --json
816
+ revo studio get <sessionId> --json
817
+ revo studio diff <sessionId> --json
818
+ revo studio patch <sessionId> --body-file patch.json --json
819
+ revo studio test <sessionId> --body-file test.json --json
820
+ revo studio cancel-test <sessionId> <testRunId> --operation-id <operationId> --json
821
+ revo studio freeze <sessionId> --body-file freeze.json --json
822
+ revo studio review <sessionId> <proposalId> --body-file review.json --json
823
+ revo studio commit <sessionId> --body-file commit.json --json
824
+ revo studio prepare <sessionId> --body-file release.json --json
825
+ revo studio activate <sessionId> --body-file activation.json --json
826
+ ```
827
+
828
+ Bodies follow the canonical Studio REST DTOs. A patch includes the expected revision and digest for every affected file; `--patch-file change.patch` can provide a V4A patch alongside its `expectedFiles` JSON body. Freeze requires the observed whole-session revision. Review names the exact proposal digest and decision, with explicit reasons for any accepted test waiver. Commit names that approved proposal and digest. Prepare names the committed release; activate also requires the observed active generation. Commit stores source while the previous runtime release remains active until explicit activation.
829
+
830
+ Additional actions are `create`, `update`, `delete`, `files`, `file <fileId>`, `events`, `chat`, `message`, `search --q`, `attach`, `fork`, `preview-rebase`, `rebase`, `share`, `participant`, `presence`, `baseline`, and `rollback`. Mutations print their operation ID. Reuse it via the JSON body or `--operation-id <uuid>` for an exact retry; changing a request while reusing its ID is rejected. No Studio command creates test waivers, commits, activates or starts another agent automatically.
831
+
832
+ `studio claims <sessionId>` lists advisory work declarations. `studio claim <sessionId> --body-file claim.json` declares work on either a session `studioFileId` or a `task`; `studio release-claim <sessionId> <claimId>` releases your authenticated actor's own declaration. The session owner can also clear abandoned claims; the journal records the actual releasing actor separately. Claims may overlap, do not lock files, and grant no editing or approval authority.
833
+
834
+ `studio cancel-test` cancels a queued run before execution or stops collecting a running result. Its durable response identifies whether already dispatched integration effects may continue. Repeat the same `--operation-id` to recover the original result; cancellation does not roll back external effects.