@revoengine/cli 1.0.31 → 1.0.34
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/CHANGELOG.md +25 -0
- package/README.md +152 -24
- package/dist/src/argument-contract.d.ts +17 -0
- package/dist/src/argument-contract.js +359 -0
- package/dist/src/automation-contract.generated.d.ts +56 -22
- package/dist/src/automation-contract.generated.js +68 -26
- package/dist/src/cli.js +15 -13
- package/dist/src/client.d.ts +34 -2
- package/dist/src/client.js +76 -13
- package/dist/src/commands/agents.js +5 -1
- package/dist/src/commands/auth.js +2 -0
- package/dist/src/commands/component.js +34 -17
- package/dist/src/commands/database-tables.js +15 -4
- package/dist/src/commands/database-views.js +5 -1
- package/dist/src/commands/endpoints.js +5 -1
- package/dist/src/commands/env.js +5 -1
- package/dist/src/commands/events.js +5 -1
- package/dist/src/commands/groups.js +5 -1
- package/dist/src/commands/info.js +2 -0
- package/dist/src/commands/job-templates.js +5 -1
- package/dist/src/commands/metadata.js +2 -0
- package/dist/src/commands/migrate.d.ts +2 -2
- package/dist/src/commands/migrate.js +33 -7
- package/dist/src/commands/project.js +19 -14
- package/dist/src/commands/request.js +2 -0
- package/dist/src/commands/role-groups.js +5 -1
- package/dist/src/commands/schedules.js +5 -1
- package/dist/src/commands/search.js +2 -0
- package/dist/src/commands/service-accounts.js +5 -1
- package/dist/src/commands/studio.js +2 -0
- package/dist/src/commands/terminal-browser-central-profile.d.ts +65 -0
- package/dist/src/commands/terminal-browser-central-profile.js +203 -0
- package/dist/src/commands/terminal-browser-human-input.d.ts +3 -1
- package/dist/src/commands/terminal-browser-human-input.js +3 -1
- package/dist/src/commands/terminal-browser-interaction.js +1 -1
- package/dist/src/commands/terminal-browser-live-protocol.d.ts +34 -2
- package/dist/src/commands/terminal-browser-live-protocol.js +28 -12
- package/dist/src/commands/terminal-browser-live-transport.d.ts +1 -0
- package/dist/src/commands/terminal-browser-live-transport.js +9 -5
- package/dist/src/commands/terminal-browser-live.d.ts +24 -3
- package/dist/src/commands/terminal-browser-live.js +199 -30
- package/dist/src/commands/terminal-browser-page-input.d.ts +4 -1
- package/dist/src/commands/terminal-browser-page-input.js +46 -1
- package/dist/src/commands/terminal-browser-profile-crypto.d.ts +30 -0
- package/dist/src/commands/terminal-browser-profile-crypto.js +101 -0
- package/dist/src/commands/terminal-browser-profile-import-runner.d.ts +31 -0
- package/dist/src/commands/terminal-browser-profile-import-runner.js +112 -0
- package/dist/src/commands/terminal-browser-profile-import.d.ts +28 -0
- package/dist/src/commands/terminal-browser-profile-import.js +125 -0
- package/dist/src/commands/terminal-browser-profile-import.protocol.d.ts +50 -0
- package/dist/src/commands/terminal-browser-profile-import.protocol.js +52 -0
- package/dist/src/commands/terminal-browser-profile-preferences.d.ts +1 -0
- package/dist/src/commands/terminal-browser-profile-preferences.js +16 -0
- package/dist/src/commands/terminal-browser-profile-sync.d.ts +14 -0
- package/dist/src/commands/terminal-browser-profile-sync.js +169 -0
- package/dist/src/commands/terminal-browser-profile-sync.protocol.d.ts +50 -0
- package/dist/src/commands/terminal-browser-profile-sync.protocol.js +19 -0
- package/dist/src/commands/terminal-browser-profile.d.ts +10 -1
- package/dist/src/commands/terminal-browser-profile.js +30 -4
- package/dist/src/commands/terminal-browser-recording.d.ts +39 -0
- package/dist/src/commands/terminal-browser-recording.js +74 -0
- package/dist/src/commands/terminal-browser-recording.protocol.d.ts +49 -0
- package/dist/src/commands/terminal-browser-recording.protocol.js +16 -0
- package/dist/src/commands/terminal-browser.d.ts +14 -1
- package/dist/src/commands/terminal-browser.js +98 -33
- package/dist/src/commands/terminal-file-descriptor.d.ts +9 -0
- package/dist/src/commands/terminal-file-descriptor.js +39 -0
- package/dist/src/commands/terminal-file.js +41 -6
- package/dist/src/commands/terminal-image.js +3 -31
- package/dist/src/commands/terminal-output-buffer.d.ts +18 -1
- package/dist/src/commands/terminal-output-buffer.js +95 -8
- package/dist/src/commands/terminal-process-group.d.ts +25 -0
- package/dist/src/commands/terminal-process-group.js +144 -0
- package/dist/src/commands/terminal.d.ts +3 -1
- package/dist/src/commands/terminal.js +366 -80
- package/dist/src/commands/tests.js +2 -0
- package/dist/src/component-lock.d.ts +15 -1
- package/dist/src/component-lock.js +96 -10
- package/dist/src/env-sync.js +12 -6
- package/dist/src/migration.d.ts +7 -0
- package/dist/src/migration.js +39 -21
- package/dist/src/planning-snapshot.d.ts +3 -0
- package/dist/src/planning-snapshot.js +60 -2
- package/dist/src/project.d.ts +1 -0
- package/dist/src/project.js +7 -8
- package/dist/src/resource-syncs/agent-sync.js +76 -24
- package/dist/src/resource-syncs/database-table-sync.d.ts +8 -1
- package/dist/src/resource-syncs/database-table-sync.js +66 -32
- package/dist/src/resource-syncs/database-view-sync.js +41 -28
- package/dist/src/resource-syncs/endpoint-sync.js +90 -18
- package/dist/src/resource-syncs/event-sync.js +33 -14
- package/dist/src/resource-syncs/group-sync.js +21 -11
- package/dist/src/resource-syncs/job-template-sync.js +98 -37
- package/dist/src/resource-syncs/role-group-sync.js +22 -11
- package/dist/src/resource-syncs/schedule-sync.js +26 -11
- package/dist/src/resource-syncs/service-account-sync.js +22 -11
- package/dist/src/reviewed-plan.js +3 -0
- package/dist/src/runtime-view.js +2 -18
- package/dist/src/sync-omit-command.d.ts +6 -0
- package/dist/src/sync-omit-command.js +49 -0
- package/dist/src/sync-omit-write-fence.d.ts +10 -0
- package/dist/src/sync-omit-write-fence.js +134 -0
- package/dist/src/sync-omit.d.ts +59 -0
- package/dist/src/sync-omit.js +469 -0
- package/dist/src/sync-output.d.ts +3 -3
- package/dist/src/ui.js +11 -5
- package/dist/src/update-notifier.d.ts +1 -1
- package/dist/src/update-notifier.js +2 -1
- package/dist/src/utils.js +46 -17
- package/dist/src/workspace-prune.js +11 -3
- package/dist/src/workspace-write-lock.d.ts +7 -0
- package/dist/src/workspace-write-lock.js +144 -0
- package/package.json +6 -5
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 1.0.34 — 2026-10-30
|
|
4
|
+
|
|
5
|
+
### Destination property preservation
|
|
6
|
+
|
|
7
|
+
- Added CLI-only `--omit` for all twelve tracked resource families across repository and dedicated pull/plan/push, deployment, named migration, and Component environment synchronization.
|
|
8
|
+
- Pull preserves selected properties from the existing local manifest; push/deploy preserves them from the target. Creates initialize omitted definition values from the source. `--force` continues to preserve omitted destination values.
|
|
9
|
+
- Supports nested dot paths, JSON Pointer, repeated flags and family-qualified paths. Arrays are atomic; unsupported, structural, identity and permission paths are rejected. Job input and Event legacy input aliases remain consistent.
|
|
10
|
+
- Keeps full local source integrity separate from managed comparisons and remote baselines. Updates verify preserved values, including absence and `null`; creates verify the complete source definition. Saved plans retain omission policy, source integrity and live target revision checks.
|
|
11
|
+
|
|
12
|
+
### CLI and terminal fixes
|
|
13
|
+
|
|
14
|
+
- Reject unknown options, missing values, conflicting aliases, ambiguous selectors and invalid booleans before executing the requested operation. Boolean values must be exactly `true` or `false`; bare and negated flags remain supported.
|
|
15
|
+
- Reject unsupported `--dry-run` on push/deploy and direct users to `plan`. Command help works without authentication. Command-specific `-t`/`-i` options no longer override API credentials or instance selection, and `--no-update-notifier` suppresses update checks correctly.
|
|
16
|
+
- Retain control of the terminal process group through cancellation, timeout and policy expiry, including after its leader exits. If cleanup cannot be confirmed, report uncertain execution instead of permitting automatic retry. Preserve buffered output in its original streams.
|
|
17
|
+
- Verify the opened workspace file before upload or image transport. Downloads retain the opened descriptor and check parent and temporary-file identities before committing.
|
|
18
|
+
- Protect workspace writes across CLI processes, reject stale lock snapshots, and replace JSON state atomically. Read-only plans and diffs remain available while another command holds the workspace write lock.
|
|
19
|
+
|
|
20
|
+
### Upgrade notes
|
|
21
|
+
|
|
22
|
+
- Remote mutations with `--omit` require a matching RevoEngine API whose fresh `/api/v1/me` response advertises `capabilities.atomicResourceUpdates: true`. Older APIs are rejected before writing; upgrading the CLI alone does not enable this server capability.
|
|
23
|
+
- Existing scripts that relied on ignored flags or values such as `--yes=0`, `--force=no` or `--activate=FALSE` must use supported options and boolean values.
|
|
24
|
+
- Legacy lock hashes and changes to omission ownership may require a fresh full pull and review, or the command's existing explicitly reviewed force/source-wins reconciliation. Properties that remain omitted stay destination-owned.
|
|
25
|
+
- Event and Schedule activation keeps its existing repository behavior: deployment preserves target activation and creates definitions inactive unless `--activate` is selected. Existing Studio and Browser server compatibility requirements remain unchanged.
|
package/README.md
CHANGED
|
@@ -10,11 +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.
|
|
13
|
+
## Version 1.0.34
|
|
14
14
|
|
|
15
|
-
This release
|
|
15
|
+
This release adds `--omit` to preserve selected destination properties during synchronization, stricter argument validation, terminal process cleanup, opened-file workspace checks, and protection against concurrent or interrupted workspace state writes. See the [1.0.34 changelog](CHANGELOG.md) for changes and upgrade requirements. Writes with `--omit` require the matching API capability `atomicResourceUpdates`; upgrading the CLI alone does not enable it.
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
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.
|
|
18
|
+
|
|
19
|
+
Runtime packages include all compiled modules, including native test workspace capture, Browser helpers and subprocess workers. Central browser-profile support requires matching API/Realtime and frontend changes; it is capability-gated independently from the published CLI version.
|
|
18
20
|
|
|
19
21
|
## Repository reconciliation
|
|
20
22
|
|
|
@@ -108,7 +110,7 @@ Terminal connection and execution metadata is also written under the CLI configu
|
|
|
108
110
|
|
|
109
111
|
The Agent terminal has independent command and network grants. Grants are ceilings; each execution frame carries the requested sandbox and `networkAccess=none|local|full`, so a Full grant does not silently widen a workspace or local-only call. Workspace commands keep writes inside the registered workspace and a private temporary directory; a workspace shell with external networking uses `workspace-network`. An explicit `unrestricted` command requests host file access without adding network access. A localhost development server must request Local network access to bind its port. macOS uses Seatbelt for workspace isolation and host plus local-only network; Linux uses `bwrap` and fails closed for shell Local access because enforceable localhost-only isolation is unavailable there. Missing isolation support fails closed. The runner requires a complete `terminal_policy_v2` execution frame from Realtime, including requested command/network modes, grant revision and optional expiry. New runners advertise `terminal_policy_selective_v1`: an increased grant takes effect on subsequent calls without disconnecting; a reduced grant stops only commands and Browser sessions no longer covered by the current grant or an unexpired temporary scope. Temporary scope expiry stops affected work and closes Browser sessions using that scope. Workspace patches and stdin for a running process are supported. A personal API key is required.
|
|
110
112
|
|
|
111
|
-
Browser actions use Playwright's Chromium headless
|
|
113
|
+
Browser actions use Playwright's full Chromium in its standard headless mode. The CLI's npm install downloads that browser into Playwright's per-user cache without requiring Python 3; a separate Chrome installation is not required. If npm scripts were disabled or the download was interrupted, reinstall the CLI with scripts enabled before using Browser. Linux hosts still need Playwright's system libraries; an administrator can install them with `npx playwright install-deps chromium`.
|
|
112
114
|
|
|
113
115
|
On macOS, workspace commands may use Unix-domain sockets only inside their own private temporary directory. This lets build tools exchange worker messages without enabling IP networking or access to workspace, other-command or host-service sockets. Local development servers still need Local network access and must bind to localhost. Ordinary process deadlines cover the whole lifetime, not startup. The runner advertises `background_shell_v1`: `terminal.start` with `background=true` and `timeout_ms=null` keeps a dev server or watcher on the existing execution ID without the ordinary lifetime timer. Status, output, stdin, PTY and cancel remain available; hiding the terminal view does not stop the process. Scope expiry, revocation, runner stop and the two-minute (120-second) disconnect grace still apply. Reuse a healthy project server or check fresh HTTP readiness after starting it.
|
|
114
116
|
|
|
@@ -141,32 +143,79 @@ web loading until upgraded and reconnected.
|
|
|
141
143
|
|
|
142
144
|
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.
|
|
143
145
|
|
|
146
|
+
Current runners also negotiate `terminal_output_capture_v1` with durable resume: shell output can be retained separately (up to 1,000,000,000 bytes (decimal 1 GB) and 1,000,000 chunks / 24 hours centrally) from the bounded 100 KB execution preview, and reloaded using the same execution without running its command again. Older servers keep their existing preview behavior.
|
|
147
|
+
|
|
148
|
+
Unacknowledged shell output uses a private process-local disk spool and an ACK-driven 256 KB estimated wire window. Reconnect sends only uncommitted output; completion follows its committed ACKs. Capture quota or spool-write failure is explicitly partial and does not terminate or replay the command. The spool is removed after result acknowledgement, resume rejection, or runner shutdown; it does not recover a process after a CLI crash. The separate local runner log retains its 10 MB limit.
|
|
149
|
+
|
|
144
150
|
Current runners advertise `terminal_workspaces_v1`, `browser_control_v1`, `file_transfer_v1` and `terminal_resume_durable_v1`. When Realtime confirms durable resume support, output is retained until the server acknowledges its PostgreSQL commit; reconnect resumes the same execution from the last committed output sequence. Redis loss alone does not stop the PTY. Older servers remain compatible without advertising durable recovery. This protocol preserves a running CLI process; it does not restore processes after a CLI or machine crash. Gateway can request socket reconnect without stopping the CLI. Temporary transport/dependency failures retry and resume within two minutes (120 seconds); authentication failures and revocation stop retry. Newly installed services stop on fatal authentication and restart other failed processes. Reinstall existing services to adopt that supervisor behavior. CLI stop does not persist local processes or browser cookies. Changing workspace grant revision conservatively terminates workspace-bound work and contexts.
|
|
145
151
|
|
|
146
152
|
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.
|
|
147
153
|
|
|
148
|
-
#### Remember browser authentication
|
|
154
|
+
#### Remember browser authentication in Vault
|
|
149
155
|
|
|
150
|
-
|
|
156
|
+
Connect the approved workspace normally:
|
|
151
157
|
|
|
152
158
|
```bash
|
|
153
|
-
revo terminal connect --workspace "$HOME/projects/my-project" --name "Work Mac"
|
|
154
|
-
revo terminal browser-profile forget --workspace "$HOME/projects/my-project" --terminal-id <terminal-uuid> --browser-profile "AP work"
|
|
159
|
+
revo terminal connect --workspace "$HOME/projects/my-project" --name "Work Mac"
|
|
155
160
|
```
|
|
156
161
|
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
162
|
+
Create website profiles in Settings → Vault → Browser profiles. Assign each profile
|
|
163
|
+
to approved terminal workspaces and grant its use to selected users/groups. Sharing
|
|
164
|
+
a terminal does not share a login. Live Preview selects assigned profiles; model
|
|
165
|
+
actions discover only authorized metadata and use explicit profile/session refs.
|
|
166
|
+
Each profile opens an independent context with cookies, localStorage and IndexedDB.
|
|
167
|
+
A busy profile cannot be stolen.
|
|
168
|
+
|
|
169
|
+
The v2 runner restores central profiles in memory on macOS, Linux and service
|
|
170
|
+
runners without a Keychain dependency. Revo wraps each profile data key with its
|
|
171
|
+
Vault deployment key and seals only that profile key to the current runner
|
|
172
|
+
connection. State uploads are encrypted, revision-bound and verified before commit.
|
|
173
|
+
A failed save retains the last confirmed cloud revision. Revocation and network
|
|
174
|
+
expiry close affected contexts; uncertain writes are not silently replayed.
|
|
175
|
+
The snapshot captures website-owned authentication state, not entered form values.
|
|
176
|
+
A saved revision does not certify successful login or extend provider session life.
|
|
177
|
+
|
|
178
|
+
The obsolete `terminal connect --browser-profile` flag is rejected. Existing local
|
|
179
|
+
encrypted snapshots remain untouched unless you explicitly migrate them through
|
|
180
|
+
Live Preview → Browser settings → Import an older local profile on an updated
|
|
181
|
+
foreground macOS runner. This creates a new private Vault profile assigned to the
|
|
182
|
+
source workspace. The source is kept by default; optional cleanup runs only after
|
|
183
|
+
the uploaded version is downloaded, decrypted and restored successfully in native
|
|
184
|
+
Chromium. Status checks never replay an import. Linux and service runners restore
|
|
185
|
+
central profiles without the legacy-import capability or a Keychain dependency.
|
|
186
|
+
The legacy `terminal browser-profile forget`
|
|
187
|
+
command remains available for explicitly removing a local snapshot and its Keychain
|
|
188
|
+
key; it does not revoke the website's server-side login.
|
|
189
|
+
|
|
190
|
+
Live Preview uses a separate authenticated outbound Realtime WebSocket. It streams the active tab and SSO popups as JPEG frames at a configurable 5–60 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.
|
|
191
|
+
|
|
192
|
+
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. Central profile selection opens another context and preserves existing tabs. Profile owner controls in Vault clear or remove saved authentication and manage use grants, workspace assignments and active sessions. A grantee cannot expand profile access.
|
|
193
|
+
|
|
194
|
+
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. Central v2 profiles work without an OS credential store; older runners are capability-gated.
|
|
195
|
+
|
|
196
|
+
Live Preview uses full Chromium in its standard headless mode. The CLI installation
|
|
197
|
+
installs the matching browser; existing installations can run `npx playwright-core
|
|
198
|
+
install chromium` from their CLI package directory after upgrading. Workspace browser
|
|
199
|
+
settings are managed in Revo: preview 5–60 FPS, viewport size, recording destination
|
|
200
|
+
and explicit Always record. A `browser_recording_session_v1` runner applies profile
|
|
201
|
+
defaults (or workspace defaults when inherited) before the first native navigation.
|
|
202
|
+
Native WebM encoding uses the selected viewport and 5–60 FPS setting. Verify the
|
|
203
|
+
finalized file before sharing it: encoded FPS does not guarantee that every frame
|
|
204
|
+
contains a distinct browser update. Updated CLI capture requires its matching Chromium.
|
|
205
|
+
Always record starts without opening Live Preview; Storage/Both uploads completed
|
|
206
|
+
30-second WebM segments in the background. Live viewing remains on demand, and
|
|
207
|
+
closing an observe preview does not stop either automatic or manually started
|
|
208
|
+
recording. A normal browser-session close flushes the last segment. Private control
|
|
209
|
+
and authentication pause recording; Finish & resume reports the resumed segment.
|
|
210
|
+
Storage destinations are resolved by Revo: personal Assistant recordings use the actor’s Private Storage; autonomous-Agent recordings use the Agent’s linked workspace and its access rules. The terminal owner and CLI connect flags do not select this destination. Local-device recording paths remain unchanged.
|
|
211
|
+
|
|
212
|
+
Saved Revo recordings appear in the preview Sources list even after the browser
|
|
213
|
+
session closes. Connection loss, expired/revoked scope or a failed upload stops
|
|
214
|
+
background recording; failed local segments are retained without blindly replaying
|
|
215
|
+
the PUT. Matching API/Realtime and an upgraded runner are required. Provider challenges may
|
|
216
|
+
still reject automated browsing; no spoofed headers or challenge bypass is enabled.
|
|
217
|
+
|
|
218
|
+
For explicit cleanup of an older local snapshot, `terminal browser-profile forget` requires its workspace and selected terminal, authenticates the actor with the current API profile, and removes only that local snapshot and Keychain key. It rejects a profile currently in use; close its browser or stop its runner first. Manage central profiles and their grants in Revo Vault. Forgetting a legacy local snapshot does not remove a Vault profile or revoke the website's server-side login.
|
|
170
219
|
|
|
171
220
|
`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.
|
|
172
221
|
|
|
@@ -308,11 +357,11 @@ revo pull \
|
|
|
308
357
|
--yes
|
|
309
358
|
```
|
|
310
359
|
|
|
311
|
-
|
|
360
|
+
Select pull resources with `--all`, `--resources`, or positional family names. For example, `revo pull databases --omit=name --yes` pulls Database Tables while preserving names in existing local manifests. Pull writes resources in dependency order and records the source baseline under the authenticated instance ID. Add `--skip-groups` to omit Group and Role Group resources from the selected scope.
|
|
312
361
|
|
|
313
362
|
Repository pull, plan, and deployment use Stable Keys for Component identity, including projects with a legacy UUID lock or no explicit `componentIdentity` setting. Pull reports resources without a Stable Key as unmanaged WIP and skips them while continuing with managed resources; `--force` does not assign missing keys or include WIP resources.
|
|
314
363
|
|
|
315
|
-
A normal pull protects locally changed files and does not remove source-deleted manifests. After review, `pull --force` replaces managed resource directories and prunes managed manifests that no longer exist on the source. Keep hand-written files outside generated resource directories.
|
|
364
|
+
A normal pull protects locally changed files and does not remove source-deleted manifests. With `--omit`, differences confined to omitted properties do not block the pull; those existing local values remain intact. After review, `pull --force` replaces managed resource directories and prunes managed manifests that no longer exist on the source. Omitted properties in retained manifests remain local even with `--force`. Keep hand-written files outside generated resource directories.
|
|
316
365
|
|
|
317
366
|
### Review and deploy the repository
|
|
318
367
|
|
|
@@ -473,7 +522,7 @@ Older Event manifests without `custom` must be refreshed with `revo events pull`
|
|
|
473
522
|
|
|
474
523
|
Event and Schedule manifests retain runtime `input` (a JSON object) and `inputMode` at the top level. Pull, plan, push, migration and readback verification include both fields. Supported modes are `override` (shallow overlay onto Job template input), `deep_override` (nested object overlay, replacing arrays and retaining null values), and `replace` (whole-input replacement, including clearing it with `{}`). The CLI migrates these definitions; the backend resolves the Job input. Unknown modes, null/scalar/array input and duplicate top-level/extension fields block writes, including with `--force`.
|
|
475
524
|
|
|
476
|
-
Previously pulled Event manifests with `extensions.input` and `extensions.inputMode` remain accepted; only those extension fields are writable. A fresh pull writes them at the top level. Old Event lock hashes are recognized using the complete live input values, so they cannot hide remote drift. Other extension fields still block deployment.
|
|
525
|
+
Previously pulled Event manifests with `extensions.input` and `extensions.inputMode` remain accepted; only those extension fields are writable. A fresh pull writes them at the top level. With `--omit`, both layouts share runtime ownership and pulls retain the existing destination layout while refreshing managed nested siblings. Omitting all `extensions` also preserves runtime input and mode. Old Event lock hashes are recognized using the complete live input values, so they cannot hide remote drift. Other extension fields still block deployment.
|
|
477
526
|
|
|
478
527
|
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.
|
|
479
528
|
|
|
@@ -546,6 +595,10 @@ RAW_SQL validation sends `take: 0` without an `output` overlay, using the backen
|
|
|
546
595
|
|
|
547
596
|
Table Stable Keys match resources across instances; a table name is the physical SQL name. Dedicated `database-tables plan/push` leaves table renames and column removals for manual handling, even with `--force`. Repository `plan/deploy` and named `migrate` use a broader source-wins policy: they can rename tables and apply supported column changes, while column removal requires `--force`. Table kind, partition parent or bounds, unsupported array changes, and ambiguous identities remain blocked. Every accepted write needs portable readback verification before its lock baseline advances.
|
|
548
597
|
|
|
598
|
+
Durable Database Operations require Platform 1.7.0. Older instances returning a completed Table synchronously remain supported for ordinary schema writes. Schema writes use durable Database Operations when the target instance supports them. The CLI submits with `async=true` and a UUID `Idempotency-Key`, then waits for `FINISHED` and reads the resource back before advancing the baseline. Transport retries reuse the exact key, body and optimistic base version. A disconnected client does not cancel accepted DDL. Operations remain visible under Database Operations; a lost status/readback reports the operation ID and leaves the baseline unchanged. Full `deploy` and named migration wait before creating dependent partitions, Views, Components or other consumers.
|
|
599
|
+
|
|
600
|
+
For admission only, use one explicit table: `revo database-tables push 'Sales/Orders#1234abcd' --yes --async --json`. The result includes `status: "accepted"` and `operation: { accepted, jobId, status }`; no success/readback baseline is claimed. `--async` cannot be combined with `--all` or pruning, and full deploy rejects it. Inspect the receipt with `revo request GET /api/v1/databases/operations/<jobId>`; after `FINISHED`, rerun normal push to verify and reconcile the baseline. For a retry across CLI invocations, supply the same `--idempotency-key <uuid>` and unchanged request/base version. Standard index builds and heavy ALTER TABLE can block writes; asynchronous execution does not remove PostgreSQL DDL locks.
|
|
601
|
+
|
|
549
602
|
Root-table columns can carry unique, non-empty Stable Keys in `definition[].metadata.<stable-key-name>`. `metadata plan/apply` can backfill missing root-column keys; partitions inherit the root definition. Existing column keys are immutable even with `--force`, and malformed or duplicate keys block backfill. A shared key matches columns before exact-name fallback, and writes attach the live target column ID. Source column IDs and reserved `__*` metadata never become portable column identity.
|
|
550
603
|
|
|
551
604
|
Dedicated push allows reviewed key-matched changes to existing columns, including name, type, default, nullability, array, primary-key, unique, and index fields. These operations can scan, lock, rewrite, or validate live data. Exact-name matching remains a fallback for safe presentation changes and an ordinary nullable column addition; it never guesses a rename. A required, defaulted, indexed, unique, or primary-key addition needs a unique column Stable Key. Structural changes to an existing unkeyed column and unkeyed operational additions remain manual. Active Database Views block dependent column renames, removals, type changes, and array changes at plan time and again before the write.
|
|
@@ -599,6 +652,40 @@ revo component debug <componentId> --read-only=false
|
|
|
599
652
|
|
|
600
653
|
Use low-level `request` carefully; it bypasses the higher-level migration planner.
|
|
601
654
|
|
|
655
|
+
## Command arguments and local workspace safety
|
|
656
|
+
|
|
657
|
+
The next CLI release rejects unknown options, missing option values and unsupported
|
|
658
|
+
option combinations before authentication or execution. Boolean options accept a
|
|
659
|
+
bare flag, `--flag=true`, `--flag=false`, or `--no-flag`; explicit values must be
|
|
660
|
+
the lowercase strings `true` or `false`. Values such as `0`, `1`, `no`, `FALSE`
|
|
661
|
+
and empty strings are errors, and conflicting repeated options are rejected.
|
|
662
|
+
For example, use `--no-force` rather than `--force=no`.
|
|
663
|
+
|
|
664
|
+
Named migration commands accept `--dry-run` to follow their read-only plan flow;
|
|
665
|
+
`env apply` supports it too. Use the corresponding `plan` command to preview
|
|
666
|
+
dedicated pushes, and `revo plan` to preview `revo deploy`.
|
|
667
|
+
Passing `--dry-run` to an unsupported command is an error; it never authorizes a
|
|
668
|
+
write. `revo <command> --help` shows help without connecting or executing.
|
|
669
|
+
Conflicting aliases are rejected as well as repeated values. Terminal connection
|
|
670
|
+
commands do not accept a child command or hidden options after `--`; raw request
|
|
671
|
+
JSON and query values remain data.
|
|
672
|
+
|
|
673
|
+
Commands that modify a workspace or its baseline take an exclusive local project
|
|
674
|
+
lock. A second writer fails before making changes; finish the active command and
|
|
675
|
+
retry. Read-only plan and diff commands remain available. Locks from a confirmed
|
|
676
|
+
dead process can be reclaimed; a live or unverifiable owner is never evicted just
|
|
677
|
+
because time has passed. A stale baseline snapshot is rejected rather than
|
|
678
|
+
replacing updates from another process. JSON state is written through a private
|
|
679
|
+
temporary file and atomic replacement, retaining the previous valid file if the
|
|
680
|
+
write fails before replacement.
|
|
681
|
+
|
|
682
|
+
Project init/update excludes the transient `.revoengine/workspace-write.lock/`
|
|
683
|
+
directory from Git. Keep `revo.lock.json` under its existing repository policy;
|
|
684
|
+
the operational writer lock is separate from that baseline file.
|
|
685
|
+
|
|
686
|
+
These local safeguards are separate from the target API's optimistic version
|
|
687
|
+
checks and do not make a multi-resource deployment one remote transaction.
|
|
688
|
+
|
|
602
689
|
## HTTP diagnostics
|
|
603
690
|
|
|
604
691
|
Enable a per-invocation HTTP trace in `.revoengine/revo.lock.json`:
|
|
@@ -702,6 +789,47 @@ MCP URLs must use public HTTPS without embedded credentials, query or fragment.
|
|
|
702
789
|
Agent and Agent Plugin synchronization is upsert-only. Repository prune blocks deletion of either family; retained Agents and inline/registry plugin references also protect Components, Groups and Service Accounts from unsafe pruning. Existing Service Account synchronization remains unchanged, including target-local credentials and membership policy.
|
|
703
790
|
|
|
704
791
|
|
|
792
|
+
### Preserve destination properties with `--omit`
|
|
793
|
+
|
|
794
|
+
`--omit` is an invocation-only CLI policy for all twelve resource families. Use it with every repository and dedicated family `pull`, repository `diff`/`plan`/`deploy`, dedicated family `plan`/`push`, named `migrate plan`/`run`/`verify`, and Component `env diff`/`apply`. On pull, the destination is the existing local manifest: selected properties stay local while the other fields refresh from the remote resource. On push or deploy, selected properties stay on the remote target. Resource metadata does not configure omission.
|
|
795
|
+
|
|
796
|
+
```bash
|
|
797
|
+
revo pull databases --omit=name --yes
|
|
798
|
+
revo pull --all --omit='job-template:inputs,endpoint:options.input' --yes
|
|
799
|
+
revo job-templates pull --all --omit='inputs,options.retry.maxAttempts'
|
|
800
|
+
revo job-templates plan --all --omit='inputs,options.retry.maxAttempts'
|
|
801
|
+
revo job-templates push --all --yes --omit='inputs,options.retry.maxAttempts'
|
|
802
|
+
|
|
803
|
+
revo plan --prune --omit='job-template:inputs,endpoint:options.input' --out reviewed-plan.json
|
|
804
|
+
revo deploy --prune --yes --reviewed-plan reviewed-plan.json \
|
|
805
|
+
--omit='job-template:inputs,endpoint:options.input'
|
|
806
|
+
```
|
|
807
|
+
|
|
808
|
+
An unqualified path must be supported by every selected family. Qualify family-specific fields in a mixed workspace, as above; a misspelled, unsupported, or out-of-scope path fails before writes. `--omit=name` applies to every selected family. Comma-separated paths and repeated `--omit` flags combine. Use dot paths for ordinary keys or JSON Pointer for literal dots and slashes, for example `--omit='endpoint:/options/input/feature.flag'`. Arrays are atomic: omit their complete property; indexes and wildcards are rejected.
|
|
809
|
+
|
|
810
|
+
| Resource family | Configurable omission examples |
|
|
811
|
+
| --- | --- |
|
|
812
|
+
| `database-table`, `database-view` | `name`, `category`, `description`, `metadata.label` |
|
|
813
|
+
| `component` | `name`, `description` (alias of `desc`), `active`, `testConfig`, `metadata.label` |
|
|
814
|
+
| `job-template` | `name`, `category`, `description`, `timeout`, `inputs`, `options.retry.maxAttempts` |
|
|
815
|
+
| `endpoint` | `name`, `category`, `description`, `active`, `timeout`, `options.input.tenant` |
|
|
816
|
+
| `schedule` | `name`, `category`, `description`, `cron`, `timezone`, `input.tenant`, `inputMode` |
|
|
817
|
+
| `event` | `name`, `category`, `description`, `filter`, `input.tenant`, `inputMode` |
|
|
818
|
+
| `group`, `role-group` | `name`, `category`, `description`, `metadata.label` |
|
|
819
|
+
| `service-account` | `name`, `metadata.label` |
|
|
820
|
+
| `agent` | `name`, `description`, `definition.config.model`, `definition.policy.maxTicks` |
|
|
821
|
+
| `agent-plugin` | `name`, `category`, `description`, `active`, `definition.timeoutMs` |
|
|
822
|
+
|
|
823
|
+
The first pull of a resource seeds its complete remote definition, including properties named by `--omit`. Later pulls preserve those properties from the existing local manifest, including nested values and absent or `null` fields. Normal pulls still protect changes to managed local fields. `--force` replaces conflicting managed fields while preserving omitted local properties. The remote environment baseline records the incoming instance state; a separate full local source proof records the complete definition written to disk.
|
|
824
|
+
|
|
825
|
+
Omitted properties do not contribute to managed differences or content conflicts. Existing targets retain their current values when another managed property changes, including nested siblings and the distinction between absent and `null`. Unchanged Job/Endpoint option envelopes are left out of update requests. If an actual option change would normalize an ignored legacy missing/null field, the CLI rejects it before writing; align the target defaults or omit the complete `options` envelope. Whole Endpoint `options` omission also blocks a conflicting schema-binding change. `--force` still preserves these properties. New resources use complete source values as their initial configuration and verify the full source definition, including omitted properties; omission never supplies missing creation fields. Job `inputs` and `options.input` aliases share ownership, including when omitting all `options`. Plugin name omission covers both its display name and writable definition name. JSON reports expose the normalized omission policy.
|
|
826
|
+
|
|
827
|
+
Identity, resource kind, Stable Key metadata, whole metadata envelopes, versions, code, database structure, routes, dependency bindings, owners, execution principals, roles, members, and built-in credential bindings cannot be omitted. Automation activation continues to use `--activate`. Omission does not authorize pruning or relax identity, dependency, request validation, or current-version checks.
|
|
828
|
+
|
|
829
|
+
The CLI advertises `capabilities.syncOmit` in `revo --version --json`. Before a remote mutation with `--omit`, it requires a fresh target `/api/v1/me` response with `capabilities.atomicResourceUpdates: true`; older APIs are rejected before writing, even when authentication was cached. Install the matching API safeguards before enabling this option in delivery pipelines.
|
|
830
|
+
|
|
831
|
+
Lock baselines record versioned property digests without raw configuration values, allowing comparison under the same or a broader omission policy. A legacy hash alone cannot prove unchanged managed fields; an unavailable baseline is reported as drift rather than silently converted. Equal managed definitions can adopt or refresh a baseline. Removing or narrowing omission invalidates its previous proof, because formerly ignored values were target-owned. Establish a fresh full baseline through pull without `--omit` and review, or explicitly review reconciliation through the command's existing `--force` or source-wins deployment policy. These overrides can replace managed differences and still preserve every property that remains omitted. Keep the same omission policy when applying a saved reviewed plan. Reviewed deployment still fences live versions and target revisions, so a target change after review requires a fresh plan. It also fences complete managed source manifests, including source values that initialize new resources; changing an omitted local value after review requires a new plan.
|
|
832
|
+
|
|
705
833
|
### Deployment verification in 1.0.22
|
|
706
834
|
|
|
707
835
|
Portable comparison includes ordinary Component metadata and full structured Database Table / Materialized View index definitions (logical names, methods, expressions, predicates, ordering, null placement, collation, operator classes and included columns). Physical index names, resource IDs and backend-reserved metadata remain instance-local. Older table/view manifests that omitted index settings should be refreshed from the source before promotion.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import type { ParsedArgs } from './types.ts';
|
|
2
|
+
/** Keep repetitions for validation without changing the public parsed argument shape. */
|
|
3
|
+
export declare function recordParsedOption(args: ParsedArgs, name: string, value: string | boolean): void;
|
|
4
|
+
export declare function readBooleanOption(args: ParsedArgs, names: readonly string[]): boolean;
|
|
5
|
+
/** Short options owned by a command never become authentication overrides. */
|
|
6
|
+
export declare function runtimeConnectionOverrides(args: ParsedArgs): {
|
|
7
|
+
baseUrl: string | undefined;
|
|
8
|
+
token: string | undefined;
|
|
9
|
+
instance: string | undefined;
|
|
10
|
+
envName: string | undefined;
|
|
11
|
+
};
|
|
12
|
+
/** Pure preflight: no configuration, filesystem, authentication or network effects. */
|
|
13
|
+
export declare function validateCommandArguments(args: ParsedArgs, options?: {
|
|
14
|
+
allowHelp?: boolean;
|
|
15
|
+
}): void;
|
|
16
|
+
/** Terminal owns connection arguments only; a suffix after -- is not a child command. */
|
|
17
|
+
export declare function validateTerminalArguments(argv: string[]): string[];
|