vortex-cli 5.0.0__tar.gz → 6.0.0__tar.gz

{vortex_cli-5.0.0/vortex_cli.egg-info → vortex_cli-6.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vortex_cli
-Version: 5.0.0
+Version: 6.0.0
 Summary: Vortex CLI
 Author-email: Jordan Amos <jordan.amos@gmail.com>
 License: MIT License
@@ -95,16 +95,35 @@ 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)
    java_home = /usr/lib/jvm/java-17-openjdk-amd64/ ; The local path to the JRE to use. Should be the same version running on your server
    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:
@@ -131,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** application in it (`vortex clone BetTrackr`) - all optionally server-qualified (`dev:13`, `dev:bettrackr/app`, `dev:BetTrackr`). 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). Refuses to delete a clone holding local changes the server doesn't have -
+  naming each file - unless `--force` is given. Verifying that asks the server for its
+  design element hashes, so a non-forced `clean` needs a reachable `backend=gateway`
+  server; a clone it can't verify is refused, not silently deleted (`--force` needs no
+  network).
+- `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.
@@ -149,6 +180,31 @@ 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 application in the BetTrackr group
+vortex clone dev:BetTrackr      # ... on the 'dev' server
+vortex clone --group BetTrackr  # explicitly a group, never a TemplateName
+```
+
+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`, `--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
@@ -172,7 +228,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
@@ -215,6 +273,59 @@ 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. 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 always use 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.
+
 ### Interactive Wizards
 
 Run `vortex new object` or `vortex new app` without any flags to launch a step-by-step wizard:
@@ -320,5 +431,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.0 → vortex_cli-6.0.0}/README.md

@@ -51,16 +51,35 @@ 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)
    java_home = /usr/lib/jvm/java-17-openjdk-amd64/ ; The local path to the JRE to use. Should be the same version running on your server
    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:
@@ -87,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** application in it (`vortex clone BetTrackr`) - all optionally server-qualified (`dev:13`, `dev:bettrackr/app`, `dev:BetTrackr`). 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). Refuses to delete a clone holding local changes the server doesn't have -
+  naming each file - unless `--force` is given. Verifying that asks the server for its
+  design element hashes, so a non-forced `clean` needs a reachable `backend=gateway`
+  server; a clone it can't verify is refused, not silently deleted (`--force` needs no
+  network).
+- `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.
@@ -105,6 +136,31 @@ 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 application in the BetTrackr group
+vortex clone dev:BetTrackr      # ... on the 'dev' server
+vortex clone --group BetTrackr  # explicitly a group, never a TemplateName
+```
+
+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`, `--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
@@ -128,7 +184,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
@@ -171,6 +229,59 @@ 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. 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 always use 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.
+
 ### Interactive Wizards
 
 Run `vortex new object` or `vortex new app` without any flags to launch a step-by-step wizard:
@@ -276,5 +387,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.0 → vortex_cli-6.0.0}/pyproject.toml

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