vortex-cli 5.0.1__tar.gz → 6.1.0__tar.gz

{vortex_cli-5.0.1 → vortex_cli-6.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vortex_cli
-Version: 5.0.1
+Version: 6.1.0
 Summary: Vortex CLI
 Author-email: Jordan Amos <jordan.amos@gmail.com>
 License: MIT License
@@ -95,10 +95,12 @@ While it is possible to use without it, this software has been purposefully desi
    [server1] ; This can be called whatever you want and can be referenced using the '--server' flag
    host = example.com
    port = 8080 ; we can overwrite the DEFAULT value
-   puakma_db_conn_id = 13
    username = myuser ; Optional - Prompted at runtime if not provided
    password = mypassword ; Optional - Prompted at runtime if not provided
    ; Optional
+   puakma_db_conn_id = 13 ; Optional - discovered from the server when omitted
+   backend = soap ; 'soap' (default) or 'gateway' - see The Agent Gateway below
+   gateway_path = vortex/gateway.pma ; only used when backend = gateway
    clone_with_resources = html,css,js ; resources with these extensions are always cloned - 'clone --get-resources' still clones ALL resources
    lib_path = ; optional extra jars to add to the classpath (the server's own jars are downloaded automatically - see 'vortex libs')
    workspace_folders = ~/dev/shared,notes ; extra folders to mount in the generated .code-workspace files. Relative paths resolve against the workspace root. Under [DEFAULT] they are added to every workspace; here they apply to this server's workspace (and the global one)
@@ -106,6 +108,22 @@ While it is possible to use without it, this software has been purposefully desi
    java_environment_name = JavaSE-17 ; Java Execution Environment name https://docs.osgi.org/reference/eenames.html
    ```
 
+## Upgrading to 6.0
+
+6.0 is additive - **the default behaviour is unchanged**. Every server keeps using the SOAP
+designer path unless you opt it in.
+
+- **New optional backend: the agent gateway.** Set `backend = gateway` on a server definition
+  to route supported operations through the `vortex/gateway` Puakma application instead of
+  SOAPDesigner. The default is `backend = soap`, which never contacts the gateway at all - so
+  servers without it installed are unaffected. See [The Agent Gateway](#the-agent-gateway).
+- **New commands**: `status`, `agenda`, `push`, `pull`, `render` and `undo`. `agenda`, `pull`,
+  `render` and `undo` require `backend = gateway`; `status` and `push` fall back to the
+  existing paths.
+- **`puakma_db_conn_id` is now optional.** When omitted it is discovered from the server on
+  both backends. Existing configs that set it explicitly keep working.
+- **`vortex list` gains Version and Last Modified columns** when run against a gateway server.
+
 ## Upgrading to 5.0
 
 5.0 changes some defaults you may rely on:
@@ -132,11 +150,23 @@ For a full list of commands see `--help`.
 - `code`: Open the workspace in Visual Studio Code (`-s <server>` opens that server's own workspace with exactly its jars on the Java classpath).
 - `use`: Set the default server so you don't need to pass `--server` on every command. e.g. `vortex use production`
 - `list` (or `ls`): List Puakma Applications on the server or cloned locally. (`ls` is an alias for `vortex list --local`)
-- `clone`: Clone Puakma Applications and their design objects into the workspace. Apps can be referenced by ID (`vortex clone 13`), by TemplateName (`vortex clone bettrackr_app`), or by group/name (`vortex clone bettrackr/app`) - all optionally server-qualified (`dev:13`, `dev:bettrackr/app`).
+- `clone`: Clone Puakma Applications and their design objects into the workspace. Apps can be referenced by ID (`vortex clone 13`), by TemplateName (`vortex clone bettrackr_app`), or by group/name (`vortex clone bettrackr/app`). A bare application group clones every active, non-inherited application in it (`vortex clone BetTrackr`; add `--all`/`-a` for the disabled and inherited ones too) - all optionally server-qualified (`dev:13`, `dev:bettrackr/app`, `dev:BetTrackr`). `--reclone` re-clones what is already cloned: every server's clones, or one server's with `--server`. See [Cloning a whole group](#cloning-a-whole-group).
 - `watch`: Watch the workspace for changes to Design Objects and automatically upload them to the server each app was cloned from. Watches all servers at once unless `--server` is given.
 - `clean`: Delete the locally cloned Puakma Application directories in the workspace.
-- `config`: View and manage configuration.
+  Takes optional `APP_ID`s to clean just those clones (all of the server's, if none are
+  given). Deletes immediately and needs no network - there is no undo. With `--check`
+  it first asks the server for its design element hashes and refuses to delete a clone
+  holding local changes the server doesn't have, naming each file; that needs a
+  reachable `backend=gateway` server, and a clone it can't verify is refused rather
+  than silently deleted.
+- `config`: View and manage configuration. `--check-gateway` reports the agent gateway negotiation and which gateway roles your identity holds.
 - `log`: View the server log.
+- `status`: Show the server status - via the agent gateway when available, otherwise the raw console `status` output.
+- `agenda`: List every scheduled action with its decoded schedule, last and next run, and whether it is overdue (read-only, gateway only).
+- `push`: Upload local design files (source, compiled classes, pages, resources) to the server without a watch session - journaled and deploy-confirmed when routed via the gateway.
+- `pull`: Refresh cloned applications in place via the gateway's incremental sync - only elements changed since the last sync are downloaded. Refuses to overwrite locally modified files without `--force`.
+- `render`: Render a PAGE server-side as your identity and print it (or `--out FILE`) - see a change without a browser login (gateway only).
+- `undo`: The server-side undo journal. No arguments lists journal entries; with an entry id it dry-runs a restore, and `--confirm` writes the journaled version back (gateway only).
 - `find`: Find Design Objects of cloned applications by name.
 - `grep`: Search the contents of cloned Design Objects using a Regular Expression.
 - `new`: Create new Design Objects, Applications, or Keywords. Use `--update <ID>` to update instead. Run without flags to launch an interactive wizard.
@@ -150,6 +180,36 @@ For a full list of commands see `--help`.
 - `docs`: Open the Tornado Server Blackbook.
 - `execute`: Execute a command on the server.
 
+### Cloning a whole group
+
+`vortex clone` takes an ID, a TemplateName, an application group, or `group/name`:
+
+```
+vortex clone 13                 # by ID
+vortex clone bettrackr_app      # by TemplateName
+vortex clone bettrackr/app      # by group/name
+vortex clone BetTrackr          # every active application in the BetTrackr group
+vortex clone -a BetTrackr       # ... including its disabled and inherited ones
+vortex clone dev:BetTrackr      # ... on the 'dev' server
+vortex clone --group BetTrackr  # explicitly a group, never a TemplateName
+```
+
+A group clone skips disabled and inherited applications (the ones `vortex list`
+hides by default) unless `--all`/`-a` is given. An application you name outright -
+by ID, TemplateName or `group/name` - is always cloned, whatever its state.
+
+Groups are matched the way `vortex list --group` matches them - a
+case-insensitive substring - except that an exact (case-insensitive) group name
+always wins, so cloning `BetTrackr` never drags in `BetTrackrLegacy`. If a
+partial name still spans several groups, vortex stops and lists them rather
+than cloning the lot.
+
+A bare word is looked up as **both** a TemplateName and a group. In the rare
+case that it is genuinely both, vortex refuses to guess: use `--group NAME` for
+the group, or the ID / `group/name` for the single application. Every flag
+(`--reclone`, `--all`, `--get-resources`, `--open-urls`, `--timeout`, `--server`)
+applies to group clones as it does to single apps.
+
 ### Working with Multiple Servers
 
 Each section in `servers.ini` defines a server (hosts must be unique across
@@ -173,7 +233,9 @@ apps from several servers at the same time:
   watcher doesn't know about). Finer-grained commands that alter design
   elements (`delete`, `copy`, `new`, `compile --upload`) lock
   per-application: they are refused for apps a watch is watching and run
-  concurrently otherwise.
+  concurrently otherwise. `push` and `pull` lock the same way - per
+  application, never workspace-wide - so they can run against one app while
+  a watch holds others.
 - In VS Code, app folders are listed in per-server blocks (`dev: group/app`,
   ...) with the server's jars on the Java classpath (see them in the Java
   Projects view). vscode-java's classpath settings are
@@ -216,6 +278,112 @@ hard to change by accident:
 - `vortex watch` skips protected servers unless `--include-protected` is
   given, so saving a file can never hot-deploy to production by accident.
 
+### The Agent Gateway
+
+The **agent gateway** is a JSON API served by the Puakma server itself - a companion Puakma
+application (`vortex/gateway`) that you deploy to a server. Where SOAPDesigner is a transport,
+the gateway is a transport *plus* the guarantees only server-side code can enforce:
+
+- **Role-gated operations** - every endpoint requires one declared application role, checked on
+  the server. Roles are rows in *that server's* copy of the app, so a grant on dev confers
+  nothing on prod.
+- **An undo journal** - destructive design writes snapshot the element first (bytes, metadata,
+  design params). `vortex undo` lists those snapshots and restores any of them; deleted
+  elements are recreatable.
+- **Dry-run by default** - `undo`, element deletes, single-statement DML and whole-server
+  refresh do nothing without an explicit confirmation.
+- **Deploy confirmation** - writes reply with the sizes and hashes of what is really on the
+  server now.
+- **Database guardrails** - the Puakma system database is unreachable through it, and DDL is
+  never executed, only generated as text.
+
+Opt in per server:
+
+```ini
+[dev]
+host = dev.example.com
+backend = gateway            ; default is 'soap', which never contacts the gateway
+; gateway_path = vortex/gateway.pma   (this is the default)
+```
+
+With `backend = gateway`, `watch`/`push` uploads, `delete`, `log`, `status`, `db`, `execute`
+and the journal commands route through it, and `agenda`, `pull`, `render` and `undo` become
+available. Everything the gateway does not offer goes to the **webdesign vortex API** (the
+JSON action served by `system/webdesign`) - see [SOAP-free on backend = gateway](#soap-free-on-backend--gateway).
+A `backend = gateway` server never talks to SOAPDesigner at all. Check what you are talking
+to and what you may do:
+
+```
+vortex config --check-gateway -s dev
+```
+
+**There is no fallback in either direction, by design.** A gateway refusal (for example, your
+identity lacks the required role) is reported as an error - vortex never quietly retries the
+same operation over SOAP, because that would let anyone with SOAP access bypass every role,
+journal and guardrail above. Likewise `backend = soap` never contacts the gateway. The one
+deliberate exception is the gateway application's *own* deployments, which never go through
+the gateway (webdesign on `backend = gateway`, SOAP on `backend = soap`) so that a broken
+gateway deploy never needs the gateway to fix itself.
+
+The gateway application is **not bundled with this CLI** - deploy it to a server with
+`vortex export` / `vortex import`, then run its `Setup` scheduled action. It ships its own
+`API.md`, `README.md` and `DECISIONS.md` as DOCUMENTATION design elements, so once installed
+the running server documents its own endpoints, roles and setup steps.
+
+> **Note:** the gateway's roles are only a real boundary for an identity whose *sole* route to
+> the server is the gateway. Any identity that can reach `system/webdesign` or deploy code can
+> grant itself any role. Keep webdesign access for operators; agent identities should not have
+> it.
+
+### SOAP-free on `backend = gateway`
+
+SOAPDesigner is legacy. On a `backend = gateway` server the commands the gateway does not
+cover use the JSON API of `system/webdesign`'s `vortex` action instead - with the same
+credentials, and the webdesign app's own ACL. SOAP is used only when a server is explicitly
+`backend = soap`. The data dictionary (`schema`, `db --list/--schema`) is the exception that
+proves the rule: the gateway's `dictionary` endpoint runs that same webdesign `vortex` action
+server-side behind `GatewayDBRead`/`GatewayDBWrite`, so an agent identity with no webdesign
+access gets a clean role answer rather than a login page, and a change to `vortex.java`
+needs no change to the gateway.
+
+| Command | `backend = gateway` | `backend = soap` |
+|---|---|---|
+| `push`, `watch` (modify), `compile --upload` | gateway `upload` (journalled); the gateway app itself: webdesign `PUT design` | SOAP `uploadDesign` |
+| `watch` (create / delete) | webdesign `POST` / `DELETE design` | SOAP |
+| `delete` | gateway `delete` (journalled); the gateway app itself: webdesign | SOAP |
+| `copy`, `new object` | webdesign `POST`/`PUT design`, `PUT design/params` | SOAP |
+| `new app` | webdesign `POST vortex` | SOAP `saveApplication` |
+| `new keyword` | gateway `keyword` (upsert) | SOAP `saveKeyword` |
+| `schema`, `db --list`, `db --schema` | gateway `dictionary` (webdesign's `database`/`table`/`column` routes run server-side; `GatewayDBRead`/`GatewayDBWrite`) | SOAP SQL + `savePuakma*` |
+| `export` | webdesign `ExportPMX` action | SOAP `downloadPmx` |
+| `import` | **still SOAP** - webdesign has no import route yet | SOAP `uploadPmx` |
+| `db --sql`, `list`, `log`, `execute`, `status`, `clone`, `pull` | gateway | SOAP |
+
+Where the webdesign API behaves differently from SOAP, the CLI compensates so the commands
+behave as they did. The differences that remain visible:
+
+- **Design element writes are whole-row.** The CLI reads the row back first and re-sends what
+  it does not model (the other blob, `Options`), so a `DATA`-only upload never wipes source.
+  One consequence: every write is one extra `GET`.
+- **Renaming with `new object --update --name` does not rewrite references.** SOAP's
+  `updateDesignObject` also updated design params in the app that referred to the old name;
+  the webdesign route does not. Fix `OpenAction`/`ParentPage`-style params by hand after a rename.
+- **`schema` cannot record `--default`, `--position` or the column half of `--ref`.** The
+  webdesign column write has no `DefaultValue`/`Position`/`RefColumn` fields (SOAP's
+  `savePuakmaAttribute2` had them). `--default`/`--position` are refused with a message;
+  `--ref TABLE.COLUMN` records the table and warns. Updates leave existing values untouched.
+  Extend `POST`/`PUT .../column` in webdesign's `vortex.java` to lift this.
+- **Every write flushes the application's design cache**, where SOAP flushed one element.
+- **No per-application `Developer` role check** - the webdesign app's ACL is the boundary. An
+  identity that can reach `system/webdesign` can edit every application through it.
+- **`db --list` orders by table name** (SOAP's `SELECT DISTINCT` had no order); `--schema`
+  output is identical.
+- **Database-name resolution is app-scoped.** `schema`/`db --list` find the connection whose
+  dictionary holds the tables (as SOAP did by `pmatable` count), asking locally cloned
+  applications first and scanning the server inventory only if none of them has it.
+- **`import` remains SOAP** on every backend until webdesign gains a PMX import route
+  (`SaveImportPMX` is a multipart UI form, not an API).
+
 ### Interactive Wizards
 
 Run `vortex new object` or `vortex new app` without any flags to launch a step-by-step wizard:
@@ -311,6 +479,11 @@ vortex schema mydb --add-column invoice customer_id --type BIGINT --ref customer
 vortex schema mydb --ddl invoice    # print CREATE TABLE from the dictionary
 ```
 
+On a `backend = gateway` server the dictionary is reached through webdesign's vortex API via
+the gateway's `dictionary` endpoint (`GatewayDBRead` to read, `GatewayDBWrite` to change).
+That API cannot record `--default` or `--position` (refused) nor the column half of `--ref`
+(warned) - see [SOAP-free on backend = gateway](#soap-free-on-backend--gateway).
+
 ### Agent Support Files
 
 `vortex agent` copies bundled support files into the workspace `.vscode` directory so they are
@@ -321,5 +494,12 @@ and the vortex workflow, and a `vortex.code-snippets` file with common Puakma Ja
 snippets. Existing files are never overwritten, so they are safe to customise. These files are
 also generated automatically on `vortex --init` and before `vortex code` opens the workspace.
 
+The guidance is backend-aware: on a `backend = gateway` server the skills teach the explicit
+`vortex compile` + `vortex push` deploy loop (journaled, `undo`-recoverable, no workspace lock),
+and the `vortex watch` save-to-deploy loop is scoped to `backend = soap`. Because existing files
+are never overwritten, workspaces generated before 6.0.0 keep their old watch-centric copies -
+delete a file (or the `.claude/skills` directory) and re-run `vortex agent` to pick up the
+current version.
+
 Workspaces created before AGENTS.md existed keep their full `CLAUDE.md` (existing files are
 never touched); the new `AGENTS.md` is simply added alongside it.

{vortex_cli-5.0.1 → vortex_cli-6.1.0}/README.md

@@ -51,10 +51,12 @@ While it is possible to use without it, this software has been purposefully desi
    [server1] ; This can be called whatever you want and can be referenced using the '--server' flag
    host = example.com
    port = 8080 ; we can overwrite the DEFAULT value
-   puakma_db_conn_id = 13
    username = myuser ; Optional - Prompted at runtime if not provided
    password = mypassword ; Optional - Prompted at runtime if not provided
    ; Optional
+   puakma_db_conn_id = 13 ; Optional - discovered from the server when omitted
+   backend = soap ; 'soap' (default) or 'gateway' - see The Agent Gateway below
+   gateway_path = vortex/gateway.pma ; only used when backend = gateway
    clone_with_resources = html,css,js ; resources with these extensions are always cloned - 'clone --get-resources' still clones ALL resources
    lib_path = ; optional extra jars to add to the classpath (the server's own jars are downloaded automatically - see 'vortex libs')
    workspace_folders = ~/dev/shared,notes ; extra folders to mount in the generated .code-workspace files. Relative paths resolve against the workspace root. Under [DEFAULT] they are added to every workspace; here they apply to this server's workspace (and the global one)
@@ -62,6 +64,22 @@ While it is possible to use without it, this software has been purposefully desi
    java_environment_name = JavaSE-17 ; Java Execution Environment name https://docs.osgi.org/reference/eenames.html
    ```
 
+## Upgrading to 6.0
+
+6.0 is additive - **the default behaviour is unchanged**. Every server keeps using the SOAP
+designer path unless you opt it in.
+
+- **New optional backend: the agent gateway.** Set `backend = gateway` on a server definition
+  to route supported operations through the `vortex/gateway` Puakma application instead of
+  SOAPDesigner. The default is `backend = soap`, which never contacts the gateway at all - so
+  servers without it installed are unaffected. See [The Agent Gateway](#the-agent-gateway).
+- **New commands**: `status`, `agenda`, `push`, `pull`, `render` and `undo`. `agenda`, `pull`,
+  `render` and `undo` require `backend = gateway`; `status` and `push` fall back to the
+  existing paths.
+- **`puakma_db_conn_id` is now optional.** When omitted it is discovered from the server on
+  both backends. Existing configs that set it explicitly keep working.
+- **`vortex list` gains Version and Last Modified columns** when run against a gateway server.
+
 ## Upgrading to 5.0
 
 5.0 changes some defaults you may rely on:
@@ -88,11 +106,23 @@ For a full list of commands see `--help`.
 - `code`: Open the workspace in Visual Studio Code (`-s <server>` opens that server's own workspace with exactly its jars on the Java classpath).
 - `use`: Set the default server so you don't need to pass `--server` on every command. e.g. `vortex use production`
 - `list` (or `ls`): List Puakma Applications on the server or cloned locally. (`ls` is an alias for `vortex list --local`)
-- `clone`: Clone Puakma Applications and their design objects into the workspace. Apps can be referenced by ID (`vortex clone 13`), by TemplateName (`vortex clone bettrackr_app`), or by group/name (`vortex clone bettrackr/app`) - all optionally server-qualified (`dev:13`, `dev:bettrackr/app`).
+- `clone`: Clone Puakma Applications and their design objects into the workspace. Apps can be referenced by ID (`vortex clone 13`), by TemplateName (`vortex clone bettrackr_app`), or by group/name (`vortex clone bettrackr/app`). A bare application group clones every active, non-inherited application in it (`vortex clone BetTrackr`; add `--all`/`-a` for the disabled and inherited ones too) - all optionally server-qualified (`dev:13`, `dev:bettrackr/app`, `dev:BetTrackr`). `--reclone` re-clones what is already cloned: every server's clones, or one server's with `--server`. See [Cloning a whole group](#cloning-a-whole-group).
 - `watch`: Watch the workspace for changes to Design Objects and automatically upload them to the server each app was cloned from. Watches all servers at once unless `--server` is given.
 - `clean`: Delete the locally cloned Puakma Application directories in the workspace.
-- `config`: View and manage configuration.
+  Takes optional `APP_ID`s to clean just those clones (all of the server's, if none are
+  given). Deletes immediately and needs no network - there is no undo. With `--check`
+  it first asks the server for its design element hashes and refuses to delete a clone
+  holding local changes the server doesn't have, naming each file; that needs a
+  reachable `backend=gateway` server, and a clone it can't verify is refused rather
+  than silently deleted.
+- `config`: View and manage configuration. `--check-gateway` reports the agent gateway negotiation and which gateway roles your identity holds.
 - `log`: View the server log.
+- `status`: Show the server status - via the agent gateway when available, otherwise the raw console `status` output.
+- `agenda`: List every scheduled action with its decoded schedule, last and next run, and whether it is overdue (read-only, gateway only).
+- `push`: Upload local design files (source, compiled classes, pages, resources) to the server without a watch session - journaled and deploy-confirmed when routed via the gateway.
+- `pull`: Refresh cloned applications in place via the gateway's incremental sync - only elements changed since the last sync are downloaded. Refuses to overwrite locally modified files without `--force`.
+- `render`: Render a PAGE server-side as your identity and print it (or `--out FILE`) - see a change without a browser login (gateway only).
+- `undo`: The server-side undo journal. No arguments lists journal entries; with an entry id it dry-runs a restore, and `--confirm` writes the journaled version back (gateway only).
 - `find`: Find Design Objects of cloned applications by name.
 - `grep`: Search the contents of cloned Design Objects using a Regular Expression.
 - `new`: Create new Design Objects, Applications, or Keywords. Use `--update <ID>` to update instead. Run without flags to launch an interactive wizard.
@@ -106,6 +136,36 @@ For a full list of commands see `--help`.
 - `docs`: Open the Tornado Server Blackbook.
 - `execute`: Execute a command on the server.
 
+### Cloning a whole group
+
+`vortex clone` takes an ID, a TemplateName, an application group, or `group/name`:
+
+```
+vortex clone 13                 # by ID
+vortex clone bettrackr_app      # by TemplateName
+vortex clone bettrackr/app      # by group/name
+vortex clone BetTrackr          # every active application in the BetTrackr group
+vortex clone -a BetTrackr       # ... including its disabled and inherited ones
+vortex clone dev:BetTrackr      # ... on the 'dev' server
+vortex clone --group BetTrackr  # explicitly a group, never a TemplateName
+```
+
+A group clone skips disabled and inherited applications (the ones `vortex list`
+hides by default) unless `--all`/`-a` is given. An application you name outright -
+by ID, TemplateName or `group/name` - is always cloned, whatever its state.
+
+Groups are matched the way `vortex list --group` matches them - a
+case-insensitive substring - except that an exact (case-insensitive) group name
+always wins, so cloning `BetTrackr` never drags in `BetTrackrLegacy`. If a
+partial name still spans several groups, vortex stops and lists them rather
+than cloning the lot.
+
+A bare word is looked up as **both** a TemplateName and a group. In the rare
+case that it is genuinely both, vortex refuses to guess: use `--group NAME` for
+the group, or the ID / `group/name` for the single application. Every flag
+(`--reclone`, `--all`, `--get-resources`, `--open-urls`, `--timeout`, `--server`)
+applies to group clones as it does to single apps.
+
 ### Working with Multiple Servers
 
 Each section in `servers.ini` defines a server (hosts must be unique across
@@ -129,7 +189,9 @@ apps from several servers at the same time:
   watcher doesn't know about). Finer-grained commands that alter design
   elements (`delete`, `copy`, `new`, `compile --upload`) lock
   per-application: they are refused for apps a watch is watching and run
-  concurrently otherwise.
+  concurrently otherwise. `push` and `pull` lock the same way - per
+  application, never workspace-wide - so they can run against one app while
+  a watch holds others.
 - In VS Code, app folders are listed in per-server blocks (`dev: group/app`,
   ...) with the server's jars on the Java classpath (see them in the Java
   Projects view). vscode-java's classpath settings are
@@ -172,6 +234,112 @@ hard to change by accident:
 - `vortex watch` skips protected servers unless `--include-protected` is
   given, so saving a file can never hot-deploy to production by accident.
 
+### The Agent Gateway
+
+The **agent gateway** is a JSON API served by the Puakma server itself - a companion Puakma
+application (`vortex/gateway`) that you deploy to a server. Where SOAPDesigner is a transport,
+the gateway is a transport *plus* the guarantees only server-side code can enforce:
+
+- **Role-gated operations** - every endpoint requires one declared application role, checked on
+  the server. Roles are rows in *that server's* copy of the app, so a grant on dev confers
+  nothing on prod.
+- **An undo journal** - destructive design writes snapshot the element first (bytes, metadata,
+  design params). `vortex undo` lists those snapshots and restores any of them; deleted
+  elements are recreatable.
+- **Dry-run by default** - `undo`, element deletes, single-statement DML and whole-server
+  refresh do nothing without an explicit confirmation.
+- **Deploy confirmation** - writes reply with the sizes and hashes of what is really on the
+  server now.
+- **Database guardrails** - the Puakma system database is unreachable through it, and DDL is
+  never executed, only generated as text.
+
+Opt in per server:
+
+```ini
+[dev]
+host = dev.example.com
+backend = gateway            ; default is 'soap', which never contacts the gateway
+; gateway_path = vortex/gateway.pma   (this is the default)
+```
+
+With `backend = gateway`, `watch`/`push` uploads, `delete`, `log`, `status`, `db`, `execute`
+and the journal commands route through it, and `agenda`, `pull`, `render` and `undo` become
+available. Everything the gateway does not offer goes to the **webdesign vortex API** (the
+JSON action served by `system/webdesign`) - see [SOAP-free on backend = gateway](#soap-free-on-backend--gateway).
+A `backend = gateway` server never talks to SOAPDesigner at all. Check what you are talking
+to and what you may do:
+
+```
+vortex config --check-gateway -s dev
+```
+
+**There is no fallback in either direction, by design.** A gateway refusal (for example, your
+identity lacks the required role) is reported as an error - vortex never quietly retries the
+same operation over SOAP, because that would let anyone with SOAP access bypass every role,
+journal and guardrail above. Likewise `backend = soap` never contacts the gateway. The one
+deliberate exception is the gateway application's *own* deployments, which never go through
+the gateway (webdesign on `backend = gateway`, SOAP on `backend = soap`) so that a broken
+gateway deploy never needs the gateway to fix itself.
+
+The gateway application is **not bundled with this CLI** - deploy it to a server with
+`vortex export` / `vortex import`, then run its `Setup` scheduled action. It ships its own
+`API.md`, `README.md` and `DECISIONS.md` as DOCUMENTATION design elements, so once installed
+the running server documents its own endpoints, roles and setup steps.
+
+> **Note:** the gateway's roles are only a real boundary for an identity whose *sole* route to
+> the server is the gateway. Any identity that can reach `system/webdesign` or deploy code can
+> grant itself any role. Keep webdesign access for operators; agent identities should not have
+> it.
+
+### SOAP-free on `backend = gateway`
+
+SOAPDesigner is legacy. On a `backend = gateway` server the commands the gateway does not
+cover use the JSON API of `system/webdesign`'s `vortex` action instead - with the same
+credentials, and the webdesign app's own ACL. SOAP is used only when a server is explicitly
+`backend = soap`. The data dictionary (`schema`, `db --list/--schema`) is the exception that
+proves the rule: the gateway's `dictionary` endpoint runs that same webdesign `vortex` action
+server-side behind `GatewayDBRead`/`GatewayDBWrite`, so an agent identity with no webdesign
+access gets a clean role answer rather than a login page, and a change to `vortex.java`
+needs no change to the gateway.
+
+| Command | `backend = gateway` | `backend = soap` |
+|---|---|---|
+| `push`, `watch` (modify), `compile --upload` | gateway `upload` (journalled); the gateway app itself: webdesign `PUT design` | SOAP `uploadDesign` |
+| `watch` (create / delete) | webdesign `POST` / `DELETE design` | SOAP |
+| `delete` | gateway `delete` (journalled); the gateway app itself: webdesign | SOAP |
+| `copy`, `new object` | webdesign `POST`/`PUT design`, `PUT design/params` | SOAP |
+| `new app` | webdesign `POST vortex` | SOAP `saveApplication` |
+| `new keyword` | gateway `keyword` (upsert) | SOAP `saveKeyword` |
+| `schema`, `db --list`, `db --schema` | gateway `dictionary` (webdesign's `database`/`table`/`column` routes run server-side; `GatewayDBRead`/`GatewayDBWrite`) | SOAP SQL + `savePuakma*` |
+| `export` | webdesign `ExportPMX` action | SOAP `downloadPmx` |
+| `import` | **still SOAP** - webdesign has no import route yet | SOAP `uploadPmx` |
+| `db --sql`, `list`, `log`, `execute`, `status`, `clone`, `pull` | gateway | SOAP |
+
+Where the webdesign API behaves differently from SOAP, the CLI compensates so the commands
+behave as they did. The differences that remain visible:
+
+- **Design element writes are whole-row.** The CLI reads the row back first and re-sends what
+  it does not model (the other blob, `Options`), so a `DATA`-only upload never wipes source.
+  One consequence: every write is one extra `GET`.
+- **Renaming with `new object --update --name` does not rewrite references.** SOAP's
+  `updateDesignObject` also updated design params in the app that referred to the old name;
+  the webdesign route does not. Fix `OpenAction`/`ParentPage`-style params by hand after a rename.
+- **`schema` cannot record `--default`, `--position` or the column half of `--ref`.** The
+  webdesign column write has no `DefaultValue`/`Position`/`RefColumn` fields (SOAP's
+  `savePuakmaAttribute2` had them). `--default`/`--position` are refused with a message;
+  `--ref TABLE.COLUMN` records the table and warns. Updates leave existing values untouched.
+  Extend `POST`/`PUT .../column` in webdesign's `vortex.java` to lift this.
+- **Every write flushes the application's design cache**, where SOAP flushed one element.
+- **No per-application `Developer` role check** - the webdesign app's ACL is the boundary. An
+  identity that can reach `system/webdesign` can edit every application through it.
+- **`db --list` orders by table name** (SOAP's `SELECT DISTINCT` had no order); `--schema`
+  output is identical.
+- **Database-name resolution is app-scoped.** `schema`/`db --list` find the connection whose
+  dictionary holds the tables (as SOAP did by `pmatable` count), asking locally cloned
+  applications first and scanning the server inventory only if none of them has it.
+- **`import` remains SOAP** on every backend until webdesign gains a PMX import route
+  (`SaveImportPMX` is a multipart UI form, not an API).
+
 ### Interactive Wizards
 
 Run `vortex new object` or `vortex new app` without any flags to launch a step-by-step wizard:
@@ -267,6 +435,11 @@ vortex schema mydb --add-column invoice customer_id --type BIGINT --ref customer
 vortex schema mydb --ddl invoice    # print CREATE TABLE from the dictionary
 ```
 
+On a `backend = gateway` server the dictionary is reached through webdesign's vortex API via
+the gateway's `dictionary` endpoint (`GatewayDBRead` to read, `GatewayDBWrite` to change).
+That API cannot record `--default` or `--position` (refused) nor the column half of `--ref`
+(warned) - see [SOAP-free on backend = gateway](#soap-free-on-backend--gateway).
+
 ### Agent Support Files
 
 `vortex agent` copies bundled support files into the workspace `.vscode` directory so they are
@@ -277,5 +450,12 @@ and the vortex workflow, and a `vortex.code-snippets` file with common Puakma Ja
 snippets. Existing files are never overwritten, so they are safe to customise. These files are
 also generated automatically on `vortex --init` and before `vortex code` opens the workspace.
 
+The guidance is backend-aware: on a `backend = gateway` server the skills teach the explicit
+`vortex compile` + `vortex push` deploy loop (journaled, `undo`-recoverable, no workspace lock),
+and the `vortex watch` save-to-deploy loop is scoped to `backend = soap`. Because existing files
+are never overwritten, workspaces generated before 6.0.0 keep their old watch-centric copies -
+delete a file (or the `.claude/skills` directory) and re-run `vortex agent` to pick up the
+current version.
+
 Workspaces created before AGENTS.md existed keep their full `CLAUDE.md` (existing files are
 never touched); the new `AGENTS.md` is simply added alongside it.

{vortex_cli-5.0.1 → vortex_cli-6.1.0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "vortex_cli"
-version = "5.0.1"
+version = "6.1.0"
 description = "Vortex CLI"
 requires-python = ">=3.10"
 readme = { file = "README.md", content-type = "text/markdown" }