@revoengine/cli 1.0.15 → 1.0.17

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 (51) hide show
  1. package/README.md +70 -12
  2. package/dist/src/cli.js +6 -2
  3. package/dist/src/client.d.ts +29 -3
  4. package/dist/src/client.js +92 -2
  5. package/dist/src/commands/component.js +2 -4
  6. package/dist/src/commands/index.d.ts +1 -0
  7. package/dist/src/commands/index.js +1 -0
  8. package/dist/src/commands/migrate.js +83 -20
  9. package/dist/src/commands/service-accounts.d.ts +2 -0
  10. package/dist/src/commands/service-accounts.js +149 -0
  11. package/dist/src/commands/terminal-browser.d.ts +29 -2
  12. package/dist/src/commands/terminal-browser.js +144 -35
  13. package/dist/src/commands/terminal-file.d.ts +21 -0
  14. package/dist/src/commands/terminal-file.js +160 -0
  15. package/dist/src/commands/terminal-operational-log.js +2 -2
  16. package/dist/src/commands/terminal-policy.d.ts +5 -2
  17. package/dist/src/commands/terminal-policy.js +10 -4
  18. package/dist/src/commands/terminal-reconnect-grace.js +1 -1
  19. package/dist/src/commands/terminal-sandbox.js +7 -0
  20. package/dist/src/commands/terminal-secure-browser.d.ts +1 -0
  21. package/dist/src/commands/terminal-secure-browser.js +2 -1
  22. package/dist/src/commands/terminal-service.js +4 -4
  23. package/dist/src/commands/terminal.d.ts +12 -0
  24. package/dist/src/commands/terminal.js +134 -45
  25. package/dist/src/component-lock.d.ts +4 -0
  26. package/dist/src/component-lock.js +21 -2
  27. package/dist/src/metadata-backfill.js +50 -1
  28. package/dist/src/migration.d.ts +20 -5
  29. package/dist/src/migration.js +200 -75
  30. package/dist/src/resource-inventory.d.ts +3 -2
  31. package/dist/src/resource-inventory.js +6 -1
  32. package/dist/src/resource-syncs/account-principal.d.ts +22 -0
  33. package/dist/src/resource-syncs/account-principal.js +86 -0
  34. package/dist/src/resource-syncs/group-sync.d.ts +10 -0
  35. package/dist/src/resource-syncs/group-sync.js +92 -20
  36. package/dist/src/resource-syncs/identity-migration.d.ts +19 -0
  37. package/dist/src/resource-syncs/identity-migration.js +108 -0
  38. package/dist/src/resource-syncs/job-template-sync.d.ts +4 -0
  39. package/dist/src/resource-syncs/job-template-sync.js +55 -12
  40. package/dist/src/resource-syncs/service-account-sync.d.ts +98 -0
  41. package/dist/src/resource-syncs/service-account-sync.js +620 -0
  42. package/dist/src/sync-output.js +10 -5
  43. package/dist/src/tracked-resources.d.ts +1 -1
  44. package/dist/src/tracked-resources.js +5 -1
  45. package/dist/src/types.d.ts +12 -0
  46. package/dist/src/ui.js +6 -3
  47. package/dist/src/workspace-diff.d.ts +1 -0
  48. package/dist/src/workspace-diff.js +4 -1
  49. package/dist/src/workspace-prune.d.ts +40 -0
  50. package/dist/src/workspace-prune.js +363 -0
  51. package/package.json +2 -2
package/README.md CHANGED
@@ -8,6 +8,10 @@ The CLI has three main capabilities:
8
8
  2. **Project migration** — plan, run, and verify a direct migration between two saved projects with `--from` and `--to`.
9
9
  3. **Resource synchronization** — work with one supported resource family through its dedicated `pull`, `plan`, and `push` commands.
10
10
 
11
+ ## Version 1.0.17
12
+
13
+ Repository deployment can now reconcile all tracked Stable Key definitions with `plan/deploy --prune`, review exact deletions and reuse a saved plan in CI. Retained dependencies are updated before obsolete definitions are deleted. Ordinary planner metadata is printed on one line per item; changes and diffs retain their detailed formatting. See the repository workflow below for approval, scope and failure behavior.
14
+
11
15
  ## Requirements and installation
12
16
 
13
17
  - Node.js 24 or newer
@@ -92,11 +96,28 @@ The Agent terminal has independent command and network grants. Grants are ceilin
92
96
 
93
97
  Browser actions use Playwright's Chromium headless shell. 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`.
94
98
 
95
- 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. It follows an SSO popup opened by a click or key press and returns to its opener when the popup closes. Browser sessions expire after 10 minutes idle (up to four per runner), 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. 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.
99
+ 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 three-minute disconnect grace still apply. Reuse a healthy project server or check fresh HTTP readiness after starting it.
100
+
101
+ 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.
102
+
103
+ 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.
104
+
105
+
106
+ 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.
107
+
108
+ ### Device workspaces and direct transfer
109
+
110
+ 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.
111
+
112
+ Current runners advertise `terminal_workspaces_v1`, `browser_control_v1` and `file_transfer_v1`. Gateway can request socket reconnect without stopping the CLI. Temporary transport/dependency failures retry and resume within three minutes; 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.
113
+
114
+ 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.
115
+
116
+ `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.
96
117
 
97
118
  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.
98
119
 
99
- Local Browser mode filters HTTP and WebSocket requests and disables WebRTC, WebTransport, Worker and SharedWorker before page scripts. Worker-dependent pages may not work in this mode; Chromium is not enclosed in an OS network sandbox. A temporary Local or Full network lease closes the Browser context at expiry when the current permanent grant does not cover it, including before a queued secure credential fill. A lost WebSocket connection, a controlled Realtime restart, or a temporary dependency outage retains running processes and Browser contexts for one two-minute reconnect period; repeated failures do not renew it. Receiving `ready` alone does not reset that period while executions still await resume confirmation. Handshake, ready and execution resume each have a ten-second transport deadline. Access revocation and malformed runner frames stop the runner and its processes. Grant revision changes reject older execute frames and stop only work outside the remaining permanent or temporary scope. A network upgrade preserves the original temporary lease for a subsequent downgrade.
120
+ Local Browser mode filters HTTP and WebSocket requests and disables WebRTC, WebTransport, Worker and SharedWorker before page scripts. Worker-dependent pages may not work in this mode; Chromium is not enclosed in an OS network sandbox. A temporary Local or Full network lease closes the Browser context at expiry when the current permanent grant does not cover it, including before a queued secure credential fill. A lost WebSocket connection, a controlled Realtime restart, or a temporary dependency outage retains running processes and Browser contexts for one three-minute reconnect period; repeated failures do not renew it. Receiving `ready` alone does not reset that period while executions still await resume confirmation. Handshake, ready and execution resume each have a ten-second transport deadline. Access revocation and malformed runner frames stop the runner and its processes. Grant revision changes reject older execute frames and stop only work outside the remaining permanent or temporary scope. A network upgrade preserves the original temporary lease for a subsequent downgrade.
100
121
 
101
122
  `save_image` validates the canonical path of the opened file descriptor and reads the image from that same descriptor (up to 30 MiB). It rejects the upload if the descriptor path cannot be verified, including when `lsof` is unavailable on macOS or `/proc/self/fd` cannot be resolved on Linux.
102
123
 
@@ -278,9 +299,27 @@ revo deploy --yes --json
278
299
 
279
300
  Repository deployment uses desired-source-wins upsert: it can adopt a missing baseline or overwrite target content drift with the repository state. Its Database Table policy permits supported table renames, column additions and changes, and copying foreign-reference declarations as metadata. Copying those declarations does not create physical SQL foreign-key constraints.
280
301
 
281
- `deploy --force` additionally approves supported high-impact operations reported by `plan`, including column removal, managed partition deletion, Materialized View Schedule writes, Schedule target-type changes, and Group or Role Group writes. Review them with `revo plan --force` before deployment. Force does not bypass invalid identity, missing dependencies, unsupported DDL, ambiguity, or failed verification. Root-table orphan deletion is available only through the dedicated table push.
302
+ `deploy --force` additionally approves supported high-impact operations reported by `plan`, including column removal, managed partition deletion, Materialized View Schedule writes, Schedule target-type changes, and Group or Role Group writes. Review them with `revo plan --force` before deployment. Force does not bypass invalid identity, missing dependencies, unsupported DDL, ambiguity, or failed verification. Full repository reconciliation explicitly selects these supported operations with `--prune`; it does not require `--force`.
282
303
 
283
- To remove target Components that no longer have local manifests, review `revo component plan --all --prune` and run `revo component push --all --prune --yes --force`. Prune matches target Components by the configured identity (Stable Key when enabled), even when their instance UUID or content differs from an old lock baseline. Components without that identity remain unmanaged. Before deletion, the CLI rechecks that no local manifest appeared and that the live target still matches the freshly computed plan; it verifies removal from the active catalog before clearing any selected lock baseline. `component plan --all --strict` reports drift but never deletes resources.
304
+ To reconcile all tracked families, review the complete plan and approve its deletion list:
305
+
306
+ ```bash
307
+ revo plan --prune --out reviewed-plan.json
308
+ revo deploy --prune --reviewed-plan reviewed-plan.json
309
+ # CI: approval is supplied by the pipeline's confirmation policy
310
+ revo deploy --prune --yes --reviewed-plan reviewed-plan.json
311
+ revo version --json
312
+ ```
313
+
314
+ `--prune` makes local manifests authoritative for the configured `trackedResources`. A keyed target resource absent locally is a deletion candidate even without an old lock entry. Unkeyed resources are unmanaged and preserved. This covers Components, Job Templates, Endpoints, Events, Schedules, Database Tables (including partitions), Database Views, Groups, Role Groups and Service Accounts when selected. Runtime Job executions/history and Webhook deliveries are outside this definition-sync scope; their existing lifecycle is unaffected. Choose only resource families owned by the repository: an empty selected family intentionally means deleting all its managed target definitions. Environment-local Service Accounts should be excluded from `trackedResources`.
315
+
316
+ The planner lists exact target IDs, names and Stable Keys in deletion order. Duplicate identity, retained local/unmanaged/out-of-scope consumers, system resources and deletion of the authenticated Service Account block the plan. Upserts and their readback verification run first, allowing a retained Job Template or Endpoint to move to a replacement Component. Pruning then removes obsolete consumers before dependencies. API errors or failed readback stop further deletes. The owning APIs retain their existing permission and reference guards and soft-delete semantics, including the table subtree lifecycle and view automation deactivation. Root deletion is blocked by any retained or unmanaged partition. No arbitrary implicit consumer cleanup is performed.
317
+
318
+ `plan --out <file>` saves the plan without mutation or lock changes. `deploy --reviewed-plan <file>` requires `--prune` and compares the saved deletion list, revisions, authenticated instance and tracked scope with the live plan before any write. Upserts are followed by another live prune plan comparison. Each deletion rechecks identity and definition, verifies disappearance from the active catalog and clears only the selected target baseline; verified partition deletion retains its lock tombstone. Cascading table/view operations additionally recheck the remaining dependency graph. Plans are advisory, not an atomic server-side transaction: concurrent edits can still cause API rejection or partial progress. A fresh plan is required after target drift or a failed partial deployment.
319
+
320
+ `deploy` always shows the plan before interactive confirmation; `--yes` supplies noninteractive approval. Ordinary resource rows, field names, dependency hints and metadata use one line per item. Field/value diffs, list changes and code/SQL diffs retain multiline Git-style formatting. `revo version --json` advertises `workspacePrune` and `reviewedPrunePlan` so CI can reject older releases that ignore unknown flags. Without `--prune`, repository deployment remains upsert-only.
321
+
322
+ Component-only reconciliation remains available through `revo component plan --all --prune` and `revo component push --all --prune --yes`; interactive confirmation is also supported. This matches the configured identity, rechecks local reappearance and live target drift, verifies deletion and clears only the selected environment baseline. `--force` is not required for explicit Component pruning. Named `migrate` and legacy `env apply` retain their existing scope and confirmation rules; `migrate --prune` is rejected.
284
323
 
285
324
  ## 2. Project-to-project migration
286
325
 
@@ -342,16 +381,17 @@ Full pull, deployment, and migration use this fixed dependency order:
342
381
  | 1 | `database-table` | `database-tables` | `DatabaseTables/` | Tables, columns, and partitions; destructive DDL remains guarded. |
343
382
  | 2 | `database-view` | `database-views` | `DatabaseViews/` | STRUCTURED and RAW_SQL views, including materialized views; target schemas must be ready first. |
344
383
  | 3 | `component` | `component` | `Components/` | Portable code, libraries, and elements. Libraries are deployed before executable components. |
345
- | 4 | `job-template` | `job-templates` | `JobTemplates/` | Resolves Component dependencies by Stable Key. Pull skips WIP templates without a Stable Key or with an unkeyed Component and reports each skip. |
346
- | 5 | `endpoint` | `endpoints` | `Endpoints/` | Resolves Component dependencies and route ordering. |
347
- | 6 | `schedule` | `schedules` | `Schedules/` | Targets Job Templates or Materialized Views. New schedules are inactive by default. |
348
- | 7 | `event` | `events` | `Events/` | Supports Job Template event targets. Manifests retain `custom: true/false` alongside `type`; new events are inactive by default. |
349
- | 8 | `group` | `groups` | `Groups/` | Group owners use Stable Keys; users and memberships remain target-local. |
350
- | 9 | `role-group` | `role-groups` | `RoleGroups/` | Role assignments run last; members and user identifiers remain target-local. |
384
+ | 4 | `service-account` | `service-accounts` | `ServiceAccounts/` | Owner identities are resolved before dependent Groups and Job Templates; secrets are target-local. |
385
+ | 5 | `job-template` | `job-templates` | `JobTemplates/` | Resolves Component and Service Account dependencies by Stable Key. Pull skips WIP templates without a Stable Key or with an unkeyed Component and reports each skip. |
386
+ | 6 | `endpoint` | `endpoints` | `Endpoints/` | Resolves Component dependencies and route ordering. |
387
+ | 7 | `schedule` | `schedules` | `Schedules/` | Targets Job Templates or Materialized Views. New schedules are inactive by default. |
388
+ | 8 | `event` | `events` | `Events/` | Supports Job Template event targets. Manifests retain `custom: true/false` alongside `type`; new events are inactive by default. |
389
+ | 9 | `group` | `groups` | `Groups/` | Group owners use Stable Keys; Service Account owners resolve early; human users and memberships remain target-local. |
390
+ | 10 | `role-group` | `role-groups` | `RoleGroups/` | Role assignments run last; members and user identifiers remain target-local. |
351
391
 
352
392
  Active Materialized View refresh Schedules are reported in Database View plans but do not block push, repository deployment, or named migration. Updating a view preserves Schedule activation; API write failures and readback verification failures are still reported.
353
393
 
354
- `--resources all` selects all nine families. Singular, plural, and common compact aliases are accepted where the command parser documents them, but the selectors above are the canonical values.
394
+ `--resources all` selects all ten families. Singular, plural, and common compact aliases are accepted where the command parser documents them, but the selectors above are the canonical values.
355
395
 
356
396
  Existing `database-schema` selectors and `revo database-schemas` commands remain accepted as compatibility aliases. New table manifests use `DatabaseTables/**/database-table.json`; older `DatabaseSchemas/**/database-schema.json` files remain readable and are relocated by the next successful table pull. A locally edited manifest still needs `--force` before pull replaces it. The manifest `kind` and `databaseSchemas` lock and plan keys retain their existing schema names for format compatibility.
357
397
 
@@ -430,7 +470,7 @@ Review `database-tables plan --all` before a destructive push. `database-tables
430
470
 
431
471
  `database-tables push --all --prune-partitions --yes --force` removes only previously managed partitions whose local manifests were removed. It deletes from leaves to root, refuses to remove a parent with an active child, and records a tombstone in the selected environment's lock after verified deletion. Unknown target-only partitions stay untouched. `database-tables push '<stableKey>' --prune-orphans --yes --force` can remove a target-only root with that Stable Key without a prior baseline. Before either remote deletion, the CLI rechecks live identity and dependencies; active child partitions or Database Views referencing the table block it. A successful delete is verified before the lock changes.
432
472
 
433
- `database-tables pull --prune-orphans --yes --force` removes local manifests missing from the source; it never deletes target tables. Dedicated plan reports root orphans without accepting `--prune-orphans`. Repository `deploy --force` can delete previously managed partitions but not root orphans. Named `migrate` does not prune remote tables or partitions.
473
+ `database-tables pull --prune-orphans --yes --force` removes local manifests missing from the source; it never deletes target tables. Dedicated plan reports root orphans without accepting `--prune-orphans`. Repository `deploy --force` retains its legacy partition-only removal policy; `deploy --prune` additionally reconciles all selected keyed table roots and partitions. Named `migrate` does not prune remote tables or partitions.
434
474
 
435
475
  Resource plans support `--json` for automation and generally support `--strict` as a convergence gate. Human-readable plans show changes by default and hide informational details such as dependency readiness, component hashes, owners, and size statistics; add `--hints` to show them in individual plans, `revo plan`, and `revo migrate plan`. JSON plans still include the complete diagnostic data. Run `revo --help` for resource-specific safety flags such as `--activate`, `--skip-partitions`, and prune controls.
436
476
 
@@ -501,3 +541,21 @@ npm run check
501
541
  npm test
502
542
  npm pack --dry-run
503
543
  ```
544
+
545
+ ## Service Accounts in migration
546
+
547
+ `revo metadata plan --resources service-account` and `revo metadata apply` assign Stable Keys explicitly.
548
+ `revo service-accounts pull --all`, `plan --all`, and `push --all --yes` manage the portable definition.
549
+ The same family is included in `revo pull --all`, repository `diff`/`plan`/`deploy`, and named `migrate plan`/`run`/`verify`.
550
+ Select it alone with `--resources service-account`. Named profiles (`--project`/`--env`), URL/token environment variables,
551
+ and the ordinary authenticated runtime work through the existing config resolution. `--force` retains the existing drift policy.
552
+
553
+ The portable manifest contains the Stable Key, name, and Stable Key of a Group or Service Account owner.
554
+ Group USER owners and Job Template `triggerUser` references to Service Accounts are resolved to target `userId` at write time.
555
+ Human principals are reported for manual configuration; an account with a human owner needs a target account with the exact Stable Key before it can be adopted.
556
+ A missing or circular owner dependency blocks writes. Groups and accounts are created in dependency order before their consumers.
557
+
558
+ API keys and secrets cannot be exported. Every newly created Service Account is active and has platform access but has no migrated credentials.
559
+ The push result contains `credentials: { stableKey, environment, policy: "target-local", status: "configure-manually" }`.
560
+ Existing target secrets remain local and are never compared, copied, rotated, or exposed in manifests, plans, lock files, or HTTP trace.
561
+ Memberships, ACL, other account metadata, and `metadataAdvanced` remain outside this sync contract.
package/dist/src/cli.js CHANGED
@@ -3,7 +3,7 @@ import { pathToFileURL } from 'node:url';
3
3
  import { RevoClient } from "./client.js";
4
4
  import { readComponentLock } from "./component-lock.js";
5
5
  import { getActiveEnvironmentName } from "./config.js";
6
- import { handleAuthCommand, handleComponentCommand, handleDatabaseTablesCommand, handleDatabaseViewsCommand, handleDeployCommand, handleDiffCommand, handleEndpointsCommand, handleEnvCommand, handleEventsCommand, handleGroupsCommand, handleInfoCommand, handleJobTemplatesCommand, handleMetadataCommand, handleMigrateCommand, handlePlanCommand, handlePullCommand, handleProjectCommand, handleRequestCommand, handleRoleGroupsCommand, handleSearchCommand, handleSchedulesCommand, handleTerminalCommand, } from "./commands/index.js";
6
+ import { handleAuthCommand, handleComponentCommand, handleDatabaseTablesCommand, handleDatabaseViewsCommand, handleDeployCommand, handleDiffCommand, handleEndpointsCommand, handleEnvCommand, handleEventsCommand, handleGroupsCommand, handleInfoCommand, handleJobTemplatesCommand, handleMetadataCommand, handleMigrateCommand, handlePlanCommand, handlePullCommand, handleProjectCommand, handleRequestCommand, handleRoleGroupsCommand, handleServiceAccountsCommand, handleSearchCommand, handleSchedulesCommand, handleTerminalCommand, } from "./commands/index.js";
7
7
  import { createHttpTraceSession, finalizeHttpTraceSession, withHttpTraceSession, } from "./http-trace.js";
8
8
  import { resolveProjectRoot } from "./project.js";
9
9
  import { withRequestQueue } from "./request-queue.js";
@@ -198,7 +198,7 @@ async function runMain(args, argv) {
198
198
  const command = args._[0];
199
199
  const noPositionals = args._.length === 0;
200
200
  if (command === 'version' || ((args.version !== undefined || args.V !== undefined) && noPositionals)) {
201
- print(packageVersion);
201
+ print(args.json ? { version: packageVersion, capabilities: { workspacePrune: true, reviewedPrunePlan: true } } : packageVersion);
202
202
  return;
203
203
  }
204
204
  if (command === 'info' || ((args.i === true || args.info === true) && noPositionals)) {
@@ -293,6 +293,10 @@ async function runMain(args, argv) {
293
293
  await handleRequestCommand(context);
294
294
  return;
295
295
  }
296
+ if (command === 'service-accounts') {
297
+ await handleServiceAccountsCommand(context);
298
+ return;
299
+ }
296
300
  if (command === 'role-groups') {
297
301
  await handleRoleGroupsCommand(context);
298
302
  return;
@@ -1,8 +1,10 @@
1
1
  import { RequestQueue } from './request-queue.ts';
2
- import type { ComponentRecord, DatabaseSchemaRecord, DatabaseViewRecord, EndpointRecord, EventRecord, GroupRecord, JobTemplateRecord, RoleGroupRecord, ScheduleRecord } from './types.ts';
2
+ import type { ComponentRecord, DatabaseSchemaRecord, DatabaseViewRecord, EndpointRecord, EventRecord, GroupRecord, JobTemplateRecord, RoleGroupRecord, ServiceAccountRecord, ScheduleRecord } from './types.ts';
3
+ import type { TrackableResourceType } from './tracked-resources.ts';
3
4
  export type RequestOptions = {
4
5
  query?: Record<string, unknown>;
5
6
  body?: unknown;
7
+ sensitiveAccountPayload?: boolean;
6
8
  headers?: HeadersInit;
7
9
  authGuard?: boolean;
8
10
  spinnerLabel?: string;
@@ -139,6 +141,13 @@ export type EndpointCreatePayload = Omit<EndpointWritePayload, 'version'> & {
139
141
  path: string;
140
142
  method: string;
141
143
  };
144
+ export type ServiceAccountWritePayload = {
145
+ name?: string;
146
+ metadata?: Record<string, unknown>;
147
+ ownerId?: string;
148
+ ownerType?: 'USER' | 'GROUP';
149
+ version?: number;
150
+ };
142
151
  export type RoleGroupListRequest = {
143
152
  path?: string;
144
153
  query?: Record<string, unknown>;
@@ -209,6 +218,7 @@ export type ScheduleCreatePayload = {
209
218
  targetConfig?: Record<string, unknown> | null;
210
219
  };
211
220
  export type JobTemplateUpdatePayload = {
221
+ triggerUser?: string;
212
222
  version: number;
213
223
  name?: string;
214
224
  category?: string | null;
@@ -220,6 +230,7 @@ export type JobTemplateUpdatePayload = {
220
230
  inputs?: unknown;
221
231
  };
222
232
  export type JobTemplateCreatePayload = {
233
+ triggerUser?: string;
223
234
  name: string;
224
235
  category?: string | null;
225
236
  desc?: string;
@@ -242,12 +253,12 @@ export type GroupWritePayload = {
242
253
  category?: string | null;
243
254
  desc?: string;
244
255
  ownerId?: string;
245
- ownerType?: 'GROUP';
256
+ ownerType?: 'USER' | 'GROUP';
246
257
  };
247
258
  export type GroupCreatePayload = Omit<GroupWritePayload, 'version'> & {
248
259
  name: string;
249
260
  ownerId: string;
250
- ownerType: 'GROUP';
261
+ ownerType: 'USER' | 'GROUP';
251
262
  members: string[];
252
263
  };
253
264
  export type RoleGroupWritePayload = {
@@ -394,6 +405,21 @@ export declare class RevoClient {
394
405
  createComponent(body: unknown): Promise<unknown>;
395
406
  updateComponent(componentId: string, body: unknown): Promise<unknown>;
396
407
  deleteComponent(componentId: string): Promise<ApiResponse<unknown>>;
408
+ deleteWorkspaceResource(resource: TrackableResourceType, id: string): Promise<unknown>;
409
+ private accountForSync;
410
+ getAccount(userId: string): Promise<ServiceAccountRecord>;
411
+ listAllServiceAccounts(options?: {
412
+ includeHumans?: boolean;
413
+ }): Promise<{
414
+ serviceAccounts: ServiceAccountRecord[];
415
+ }>;
416
+ getServiceAccount(userId: string): Promise<ServiceAccountRecord>;
417
+ createServiceAccount(body: ServiceAccountWritePayload & {
418
+ name: string;
419
+ ownerId: string;
420
+ ownerType: 'USER' | 'GROUP';
421
+ }): Promise<ServiceAccountRecord>;
422
+ updateServiceAccount(userId: string, body: ServiceAccountWritePayload): Promise<ServiceAccountRecord>;
397
423
  listRoleGroups(options?: RoleGroupListRequest): Promise<unknown>;
398
424
  listAllRoleGroups(): Promise<{
399
425
  roleGroups: RoleGroupRecord[];
@@ -521,7 +521,7 @@ export class RevoClient {
521
521
  const traceRequest = beginHttpTraceRequest({
522
522
  method,
523
523
  url,
524
- body: body,
524
+ body: options.sensitiveAccountPayload ? '[account payload omitted]' : body,
525
525
  context: this.environmentName ? { environment: this.environmentName } : undefined,
526
526
  });
527
527
  const maxRetries = options.maxRetries ?? this.maxRetries;
@@ -599,10 +599,13 @@ export class RevoClient {
599
599
  status: response.status,
600
600
  ok: accepted,
601
601
  responseHeaders: response.headers,
602
- responseData: data,
602
+ responseData: options.sensitiveAccountPayload ? '[account payload omitted]' : data,
603
603
  responseBytes: responseSize(data, response.headers),
604
604
  });
605
605
  if (!response.ok && response.status !== 304) {
606
+ if (options.sensitiveAccountPayload) {
607
+ data = { message: `Account request failed (HTTP ${response.status}).` };
608
+ }
606
609
  if (response.status === 401) {
607
610
  saveAuthValidationState({
608
611
  key: this.authValidationKey,
@@ -1174,6 +1177,93 @@ export class RevoClient {
1174
1177
  spinnerLabel: 'Deleting component',
1175
1178
  });
1176
1179
  }
1180
+ async deleteWorkspaceResource(resource, id) {
1181
+ const encoded = encodeURIComponent(id);
1182
+ const single = {
1183
+ component: `/api/v1/component/${encoded}`,
1184
+ 'database-table': `/api/v1/databases/${encoded}`,
1185
+ group: `/api/v1/groups/${encoded}`,
1186
+ 'role-group': `/api/v1/role-groups/${encoded}`,
1187
+ 'service-account': `/api/v1/accounts/${encoded}`,
1188
+ };
1189
+ const bulk = {
1190
+ 'job-template': '/api/v1/automation/template/delete',
1191
+ schedule: '/api/v1/automation/schedule/delete',
1192
+ event: '/api/v1/automation/event/delete',
1193
+ endpoint: '/api/v1/endpoints/delete',
1194
+ 'database-view': '/api/v1/databases/views/delete',
1195
+ };
1196
+ const requestPath = single[resource] || bulk[resource];
1197
+ if (!requestPath)
1198
+ throw new Error(`Unsupported workspace deletion family: ${resource}.`);
1199
+ return this.requestData(single[resource] ? 'DELETE' : 'POST', requestPath, {
1200
+ ...(bulk[resource] ? { body: { data: [id] } } : {}),
1201
+ maxRetries: 0,
1202
+ spinnerLabel: `Deleting ${resource}`,
1203
+ });
1204
+ }
1205
+ accountForSync(value) {
1206
+ const wrapper = isRecord(value) && isRecord(value.data) ? value.data : value;
1207
+ if (!isRecord(wrapper)) {
1208
+ throw new Error('Invalid account response.');
1209
+ }
1210
+ const record = {};
1211
+ for (const field of ['userId', 'name', 'serviceAccount', 'ownerId', 'ownerType', 'version', 'deletedAt']) {
1212
+ if (wrapper[field] !== undefined) {
1213
+ Object.assign(record, { [field]: wrapper[field] });
1214
+ }
1215
+ }
1216
+ const metadata = isRecord(wrapper.metadata) ? wrapper.metadata : wrapper.metaData;
1217
+ if (isRecord(metadata)) {
1218
+ record.metadata = metadata;
1219
+ }
1220
+ return record;
1221
+ }
1222
+ async getAccount(userId) {
1223
+ return this.accountForSync(await this.requestData('GET', `/api/v1/accounts/${encodeURIComponent(userId)}`, { sensitiveAccountPayload: true }));
1224
+ }
1225
+ async listAllServiceAccounts(options = {}) {
1226
+ const serviceAccounts = [];
1227
+ let skip = 0;
1228
+ const seenIds = new Set();
1229
+ while (true) {
1230
+ // Use unfiltered page sizes/total for offsets: /accounts also lists humans.
1231
+ const page = unwrapListPage(await this.requestData('GET', '/api/v1/accounts', {
1232
+ sensitiveAccountPayload: true,
1233
+ query: { take: COMPONENT_LIST_PAGE_SIZE, skip, count: true },
1234
+ }));
1235
+ for (const item of page.items) {
1236
+ const account = this.accountForSync(item);
1237
+ if ((account.serviceAccount === true || options.includeHumans === true) && !account.deletedAt) {
1238
+ if (!account.userId || seenIds.has(account.userId)) {
1239
+ throw new Error('Invalid or repeated account ID while listing service accounts.');
1240
+ }
1241
+ seenIds.add(account.userId);
1242
+ serviceAccounts.push(account);
1243
+ }
1244
+ }
1245
+ skip += page.items.length;
1246
+ if (page.items.length === 0 || (page.total !== null && skip >= page.total)
1247
+ || (page.total === null && page.items.length < COMPONENT_LIST_PAGE_SIZE)) {
1248
+ break;
1249
+ }
1250
+ }
1251
+ return { serviceAccounts };
1252
+ }
1253
+ async getServiceAccount(userId) {
1254
+ const account = await this.getAccount(userId);
1255
+ if (account.serviceAccount !== true || account.deletedAt) {
1256
+ throw new Error('Account is not an active service account.');
1257
+ }
1258
+ return account;
1259
+ }
1260
+ async createServiceAccount(body) {
1261
+ return this.accountForSync(await this.requestData('POST', '/api/v1/accounts/createServiceAccount', { body, sensitiveAccountPayload: true }));
1262
+ }
1263
+ async updateServiceAccount(userId, body) {
1264
+ await this.getServiceAccount(userId);
1265
+ return this.accountForSync(await this.requestData('PUT', `/api/v1/accounts/${encodeURIComponent(userId)}`, { body, sensitiveAccountPayload: true }));
1266
+ }
1177
1267
  async listRoleGroups(options = {}) {
1178
1268
  return this.requestData('GET', options.path || '/api/v1/role-groups', {
1179
1269
  query: options.query,
@@ -617,6 +617,7 @@ function migrateComponentLockIdentity(cwd, identity, localCatalog, remoteCatalog
617
617
  components: migratedComponents,
618
618
  groups: lock.groups,
619
619
  roleGroups: lock.roleGroups,
620
+ serviceAccounts: lock.serviceAccounts,
620
621
  jobTemplates: lock.jobTemplates,
621
622
  schedules: lock.schedules,
622
623
  events: lock.events,
@@ -1464,13 +1465,13 @@ export async function pushAllComponents(context, options) {
1464
1465
  migrateComponentLockIdentity(cwd, identity, buildLocalComponentCatalog(cwd, identity), remoteCatalog);
1465
1466
  }
1466
1467
  await assertNoComponentTypeTransitionBlockers(context, manifests, identity, remoteCatalog);
1467
- await confirmBulkAction(context, 'push', manifests.length + pruneCandidates.length, options.force || options.yes);
1468
1468
  if (pruneCandidates.length > 0) {
1469
1469
  printSyncNotice(println, `Pruning ${pruneCandidates.length} managed component(s) absent from the repository.`);
1470
1470
  for (const item of pruneCandidates) {
1471
1471
  println(` - ${item.identityKey || item.componentId} (${item.remoteComponentId})`);
1472
1472
  }
1473
1473
  }
1474
+ await confirmBulkAction(context, 'push', manifests.length + pruneCandidates.length, options.force || options.yes);
1474
1475
  const startedAt = Date.now();
1475
1476
  const results = [];
1476
1477
  for (const manifestPath of manifests) {
@@ -2046,9 +2047,6 @@ export async function handleComponentCommand(context) {
2046
2047
  if (prune && (!['plan', 'push'].includes(subcommand) || !all || changedScope.enabled)) {
2047
2048
  throw new Error('Component --prune requires plan --all or push --all without --changed.');
2048
2049
  }
2049
- if (prune && subcommand === 'push' && (!yes || !force)) {
2050
- throw new Error('Component push --prune requires --yes --force.');
2051
- }
2052
2050
  if (context.componentEnvironment && ['pull', 'plan', 'push'].includes(subcommand)) {
2053
2051
  const identity = resolveComponentIdentity(context);
2054
2052
  if (identity.mode !== 'stableKey') {
@@ -12,6 +12,7 @@ export * from './metadata.ts';
12
12
  export * from './migrate.ts';
13
13
  export * from './project.ts';
14
14
  export * from './request.ts';
15
+ export * from './service-accounts.ts';
15
16
  export * from './role-groups.ts';
16
17
  export * from './search.ts';
17
18
  export * from './terminal.ts';
@@ -12,6 +12,7 @@ export * from "./metadata.js";
12
12
  export * from "./migrate.js";
13
13
  export * from "./project.js";
14
14
  export * from "./request.js";
15
+ export * from "./service-accounts.js";
15
16
  export * from "./role-groups.js";
16
17
  export * from "./search.js";
17
18
  export * from "./terminal.js";