vortex-cli 8.1.0__tar.gz → 8.2.0__tar.gz

{vortex_cli-8.1.0 → vortex_cli-8.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vortex_cli
-Version: 8.1.0
+Version: 8.2.0
 Summary: Vortex CLI
 Author-email: Jordan Amos <jordan.amos@gmail.com>
 License: MIT License
@@ -106,6 +106,18 @@ 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 8.2
+
+- **`object run` runs ACTIONs, and waits.** It calls the gateway's new `POST run` (gateway
+  `AppVersion` 0.1.4 or later) instead of sending `tell agenda run` to the console, and
+  reports how long the action took, its reply and any exception (see
+  [Running an action](#running-an-action)). An older gateway refuses it with `NOT_EXPOSED`.
+  It no longer accepts a SCHEDULED_ACTION.
+- **`vortex agenda`** lists the scheduled actions AGENDA has loaded and queues one with
+  `agenda run`, refusing the cases where AGENDA would silently do nothing (see
+  [The agenda](#the-agenda)). It replaces both `object run` on a scheduled action and
+  `vortex execute tell agenda run ...`.
+
 ## Upgrading to 8.1
 
 8.1 does two things. It replaces `vortex config` with plain top-level commands that read
@@ -127,7 +139,7 @@ errors (exit 2).
 | `config --set-password` | `keyring set vortex-cli:<server> <username>` |
 | `config --sample` | `server get` (every option it reads) |
 | `execute --show-schedule` / `--refresh-agenda` / `--flush-cache` | `execute schedule` / `refresh-agenda` / `flush-cache` |
-| `execute --refresh-design N` | `app refresh-design N` |
+| `execute --refresh-design N` | `execute refresh-design N` or `app refresh N` |
 | `execute --run PATH` | `object run ID --app-id N` |
 | `status [--show-permissions] [--json]` | `vortex [-s NAME] [--show-permissions] [--json]` (no command) - plus the CLI version and the workspace |
 | `vortex` with no command (the workspace path) | the live status of the default server: `vortex-cli` and `workspace` first, then the server (`vortex --path` prints just the path) |
@@ -271,7 +283,7 @@ vortex app update   APP_ID [--name --group --description --inherit-from --templa
                     [--param NAME=VALUE ...] [--remove-param NAME ...]
 vortex app export   APP_ID... [--out-dir --exclude-source --timeout]
 vortex app import   FILE.pmx --name N --group G
-vortex app refresh-design APP_ID
+vortex app refresh  APP_ID  (alias: refresh-design)
 
 ── object ───────────────────────────────────────────────────────────────────
 vortex object get    ID --app-id ID [--show-source --show-data] [--json]
@@ -289,7 +301,7 @@ vortex object list   [QUERY] [--app-id ID [--local]] [--strict --inherits-from|-
                      --ids-only --show-params --type T...] [--json]
 vortex object grep   PATTERN [--app-id ID] [--output-paths|--output-apps]
                      [--include-resources|--type T...] [--json]
-vortex object run    ID --app-id ID
+vortex object run    ID --app-id ID [--output] [--json]
 vortex object delete ID... --app-id ID [--yes]
 
 ── keyword ──────────────────────────────────────────────────────────────────
@@ -315,6 +327,10 @@ vortex db update-column DB TABLE COLUMN --app-id ID [--name --type --size --desc
                         --cascade-delete|--no-cascade-delete]
 vortex db delete-column DB TABLE COLUMN --app-id ID [--yes]
 
+── agenda ───────────────────────────────────────────────────────────────────
+vortex agenda [list] [--app-id ID] [--json]
+vortex agenda run    ID --app-id ID [--param KEY=VALUE ...] [--refresh --force] [--json]
+
 ── Workspace ────────────────────────────────────────────────────────────────
 vortex ls        [app list filters] [--json]      = app list --local
 vortex clone     APP... [--group --reclone --all --get-resources --open-urls --timeout]
@@ -329,7 +345,8 @@ vortex code      [--refresh [--reset]] [-s]
 vortex           [-s NAME] [--show-permissions] [--json]   (the server's live status)
 vortex --path    (the workspace path)
 vortex log       [-n --source -m --errors-only|--debug-only|--info-only -k -d] [--json]
-vortex execute   CMD... | flush-cache | refresh-agenda | schedule [--json]  (alias: ex)
+vortex execute   CMD... | flush-cache | refresh-agenda | refresh-design APP_ID | schedule
+                 [--json]  (alias: ex)
 vortex server list  [--json]
 vortex server get   [NAME] [--json]
 vortex server use   NAME                                  (or: vortex use NAME)
@@ -406,27 +423,45 @@ and application write, so a manual cache flush is never required after one.
 
 `vortex execute CMD...` (or `ex`) sends any console command - the gateway's `POST console`,
 which needs `GatewaySystem`, or the SOAP console without the gateway. The words are joined,
-so no quoting is needed. Three names are shortcuts that send the exact strings the server's
+so no quoting is needed. These names are shortcuts that send the exact strings the server's
 addins match:
 
 | Shortcut | Sends | Effect |
 |---|---|---|
-| `schedule` | `tell agenda schedule` | lists every scheduled action and its next run |
+| `schedule` | `tell agenda schedule` | lists every scheduled action and its next run (raw text; `vortex agenda` parses it) |
 | `refresh-agenda` | `tell agenda refresh` | AGENDA rereads every schedule now |
+| `refresh-design APP_ID` | `tell agenda run /<webdesign_path>/RefreshDesign?&AppID=N` | rebuilds the application's design from its template, as `app refresh` does (a clone is then out of date) |
 | `flush-cache` | `tell http cache flush` | clears the design cache and all action class loaders |
 
 `tell http flush cache` is **not** a valid command: the HTTP addin only matches
 `cache flush`, and anything else does nothing, silently. Use `flush-cache`.
 
-Two console operations act on one application or object, so they live with those nouns:
-
-| Command | Sends |
-|---|---|
-| `vortex app refresh-design APP_ID` | `tell agenda run /<webdesign_path>/RefreshDesign?&AppID=N` - rebuilds the design from its template (a clone is then out of date) |
-| `vortex object run ID --app-id N` | `tell agenda run /group/app.pma/name` - runs an ACTION or SCHEDULED_ACTION now |
+`vortex app refresh APP_ID` also lives with its noun: it sends
+`tell agenda run /<webdesign_path>/RefreshDesign?&AppID=N`, which rebuilds the design from its
+template (a clone is then out of date).
+
+### Running an action
+
+`vortex object run ID --app-id N` runs an ACTION now, as your identity, and waits for it:
+the gateway's `POST run` (`GatewaySystem`) loads the action's class, executes it and replies
+with how long it took, its redirect, content type and reply size. `--output` also prints the
+action's reply (its buffer, as text). An action that throws exits 1 with `ACTION_FAILED` and
+the exception; a path with no compiled ACTION is `NOT_FOUND`.
+
+- **ACTIONs only.** A SCHEDULED_ACTION (or any other type) is `WRONG_TYPE`. Scheduled
+  actions are queued with AGENDA: `vortex agenda run ID --app-id N` ([The agenda](#the-agenda)).
+- **No client connection.** The action's `getOutputStream()` is null, as under AGENDA, so it
+  must buffer its reply (`write`/`setBuffer`); one that streams unconditionally fails with
+  the NullPointerException as its result.
+- **Synchronous.** The CLI waits up to 300 s. Behind Cloudflare (prod) the request is cut
+  at about 100 s; the action still finishes on the server - check `vortex log`.
+- **Gateway required.** It needs a gateway with the `run` route; an older gateway refuses with
+  `NOT_EXPOSED`. Earlier versions of `object run` sent `tell agenda run`, which only reached
+  scheduled actions on AGENDA's list and did nothing, silently, for an ACTION.
 
 The 8.0 flags (`--show-schedule`, `--refresh-agenda`, `--flush-cache`, `--refresh-design`,
-`--run`) were removed in 8.1.
+`--run`) were removed in 8.1. `app refresh` was `app refresh-design` in 8.1.0; the old
+name still works.
 
 ### Local clones stay in sync
 
@@ -449,7 +484,7 @@ prints the command to re-sync (`vortex clone APP_ID -s SERVER`).
 | `object copy` | the target application's clone |
 | `keyword set` / `delete` | the clone's stored keywords |
 | `compile` | writes `zbin/`; `--upload` stores the uploaded blobs |
-| `execute --refresh-design` | none - prints that the clone is out of date |
+| `app refresh` / `execute refresh-design` | none - prints that the clone is out of date |
 | `app create` / `import` / `export`, all `db` commands | none |
 
 A clone stores the design objects, the application's details (with its description), its
@@ -570,6 +605,40 @@ vortex object get 7901 --app-id 62                     # the parsed schedule
   starts; if that lands between the command's read and write, the old `LastRun` is written
   back and the action may run one interval early.
 
+### The agenda
+
+AGENDA has no API beyond its console commands, so `vortex agenda` sends them through the same
+console route as `vortex execute` (the gateway's `POST console`, `GatewaySystem`, or the SOAP
+console without the gateway) and parses the text they answer.
+
+```
+vortex agenda -s dev                     # = agenda list
+vortex agenda list --app-id 9 -s dev
+vortex agenda run 7825 --app-id 60 -s dev [--param AppID=12] [--refresh] [--force]
+```
+
+- **`list`** - `tell agenda schedule`: every scheduled action AGENDA has **loaded**, by next
+  run (server time), with the waitlist and AGENDA's counts (running, waitlisted, scheduled,
+  max at once). An action with empty `Options` is loaded as *on demand only*. Not listed: an
+  action with `Schedule=N`, one in a disabled application or an application with scheduled
+  actions disabled, and one created or renamed since AGENDA's last refresh (every 15
+  minutes). AGENDA says how many actions are running, never which.
+- **`run`** - queues a SCHEDULED_ACTION: `tell agenda run /group/app.pma/Name[?&KEY=VALUE...]`.
+  It runs as the system session when one of AGENDA's slots is free; its result is only in
+  `vortex log`. AGENDA answers that command with nothing, whatever it did, so `run` checks
+  first and sends nothing when AGENDA would not run it:
+  - `NOT_ON_AGENDA` - the action has `Schedule=N` (give it a schedule first), or it is not on
+    the loaded list. `--refresh` sends `tell agenda refresh` and checks again (for an action
+    created or renamed in the last 15 minutes).
+  - `ALREADY_QUEUED` - it is already waitlisted; AGENDA would skip it.
+  - `PREFIX_COLLISION` - AGENDA matches the path by prefix and queues it once per matching
+    item, so `.../SyncAll` would also match an item `.../Sync` and run twice. `--force` sends
+    it anyway.
+  - `WRONG_TYPE` - not a SCHEDULED_ACTION (an ACTION is run with `vortex object run`).
+- A queued run moves the action's next scheduled run (AGENDA resets it), and it can't be
+  stopped from here (`vortex execute tell agenda stop /group/app.pma/Name` asks the action to
+  quit; it has to check for that itself).
+
 ### Keyword values and secrets
 
 Keywords are an application's live configuration, and in practice they hold credentials in

{vortex_cli-8.1.0 → vortex_cli-8.2.0}/README.md

@@ -62,6 +62,18 @@ 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 8.2
+
+- **`object run` runs ACTIONs, and waits.** It calls the gateway's new `POST run` (gateway
+  `AppVersion` 0.1.4 or later) instead of sending `tell agenda run` to the console, and
+  reports how long the action took, its reply and any exception (see
+  [Running an action](#running-an-action)). An older gateway refuses it with `NOT_EXPOSED`.
+  It no longer accepts a SCHEDULED_ACTION.
+- **`vortex agenda`** lists the scheduled actions AGENDA has loaded and queues one with
+  `agenda run`, refusing the cases where AGENDA would silently do nothing (see
+  [The agenda](#the-agenda)). It replaces both `object run` on a scheduled action and
+  `vortex execute tell agenda run ...`.
+
 ## Upgrading to 8.1
 
 8.1 does two things. It replaces `vortex config` with plain top-level commands that read
@@ -83,7 +95,7 @@ errors (exit 2).
 | `config --set-password` | `keyring set vortex-cli:<server> <username>` |
 | `config --sample` | `server get` (every option it reads) |
 | `execute --show-schedule` / `--refresh-agenda` / `--flush-cache` | `execute schedule` / `refresh-agenda` / `flush-cache` |
-| `execute --refresh-design N` | `app refresh-design N` |
+| `execute --refresh-design N` | `execute refresh-design N` or `app refresh N` |
 | `execute --run PATH` | `object run ID --app-id N` |
 | `status [--show-permissions] [--json]` | `vortex [-s NAME] [--show-permissions] [--json]` (no command) - plus the CLI version and the workspace |
 | `vortex` with no command (the workspace path) | the live status of the default server: `vortex-cli` and `workspace` first, then the server (`vortex --path` prints just the path) |
@@ -227,7 +239,7 @@ vortex app update   APP_ID [--name --group --description --inherit-from --templa
                     [--param NAME=VALUE ...] [--remove-param NAME ...]
 vortex app export   APP_ID... [--out-dir --exclude-source --timeout]
 vortex app import   FILE.pmx --name N --group G
-vortex app refresh-design APP_ID
+vortex app refresh  APP_ID  (alias: refresh-design)
 
 ── object ───────────────────────────────────────────────────────────────────
 vortex object get    ID --app-id ID [--show-source --show-data] [--json]
@@ -245,7 +257,7 @@ vortex object list   [QUERY] [--app-id ID [--local]] [--strict --inherits-from|-
                      --ids-only --show-params --type T...] [--json]
 vortex object grep   PATTERN [--app-id ID] [--output-paths|--output-apps]
                      [--include-resources|--type T...] [--json]
-vortex object run    ID --app-id ID
+vortex object run    ID --app-id ID [--output] [--json]
 vortex object delete ID... --app-id ID [--yes]
 
 ── keyword ──────────────────────────────────────────────────────────────────
@@ -271,6 +283,10 @@ vortex db update-column DB TABLE COLUMN --app-id ID [--name --type --size --desc
                         --cascade-delete|--no-cascade-delete]
 vortex db delete-column DB TABLE COLUMN --app-id ID [--yes]
 
+── agenda ───────────────────────────────────────────────────────────────────
+vortex agenda [list] [--app-id ID] [--json]
+vortex agenda run    ID --app-id ID [--param KEY=VALUE ...] [--refresh --force] [--json]
+
 ── Workspace ────────────────────────────────────────────────────────────────
 vortex ls        [app list filters] [--json]      = app list --local
 vortex clone     APP... [--group --reclone --all --get-resources --open-urls --timeout]
@@ -285,7 +301,8 @@ vortex code      [--refresh [--reset]] [-s]
 vortex           [-s NAME] [--show-permissions] [--json]   (the server's live status)
 vortex --path    (the workspace path)
 vortex log       [-n --source -m --errors-only|--debug-only|--info-only -k -d] [--json]
-vortex execute   CMD... | flush-cache | refresh-agenda | schedule [--json]  (alias: ex)
+vortex execute   CMD... | flush-cache | refresh-agenda | refresh-design APP_ID | schedule
+                 [--json]  (alias: ex)
 vortex server list  [--json]
 vortex server get   [NAME] [--json]
 vortex server use   NAME                                  (or: vortex use NAME)
@@ -362,27 +379,45 @@ and application write, so a manual cache flush is never required after one.
 
 `vortex execute CMD...` (or `ex`) sends any console command - the gateway's `POST console`,
 which needs `GatewaySystem`, or the SOAP console without the gateway. The words are joined,
-so no quoting is needed. Three names are shortcuts that send the exact strings the server's
+so no quoting is needed. These names are shortcuts that send the exact strings the server's
 addins match:
 
 | Shortcut | Sends | Effect |
 |---|---|---|
-| `schedule` | `tell agenda schedule` | lists every scheduled action and its next run |
+| `schedule` | `tell agenda schedule` | lists every scheduled action and its next run (raw text; `vortex agenda` parses it) |
 | `refresh-agenda` | `tell agenda refresh` | AGENDA rereads every schedule now |
+| `refresh-design APP_ID` | `tell agenda run /<webdesign_path>/RefreshDesign?&AppID=N` | rebuilds the application's design from its template, as `app refresh` does (a clone is then out of date) |
 | `flush-cache` | `tell http cache flush` | clears the design cache and all action class loaders |
 
 `tell http flush cache` is **not** a valid command: the HTTP addin only matches
 `cache flush`, and anything else does nothing, silently. Use `flush-cache`.
 
-Two console operations act on one application or object, so they live with those nouns:
-
-| Command | Sends |
-|---|---|
-| `vortex app refresh-design APP_ID` | `tell agenda run /<webdesign_path>/RefreshDesign?&AppID=N` - rebuilds the design from its template (a clone is then out of date) |
-| `vortex object run ID --app-id N` | `tell agenda run /group/app.pma/name` - runs an ACTION or SCHEDULED_ACTION now |
+`vortex app refresh APP_ID` also lives with its noun: it sends
+`tell agenda run /<webdesign_path>/RefreshDesign?&AppID=N`, which rebuilds the design from its
+template (a clone is then out of date).
+
+### Running an action
+
+`vortex object run ID --app-id N` runs an ACTION now, as your identity, and waits for it:
+the gateway's `POST run` (`GatewaySystem`) loads the action's class, executes it and replies
+with how long it took, its redirect, content type and reply size. `--output` also prints the
+action's reply (its buffer, as text). An action that throws exits 1 with `ACTION_FAILED` and
+the exception; a path with no compiled ACTION is `NOT_FOUND`.
+
+- **ACTIONs only.** A SCHEDULED_ACTION (or any other type) is `WRONG_TYPE`. Scheduled
+  actions are queued with AGENDA: `vortex agenda run ID --app-id N` ([The agenda](#the-agenda)).
+- **No client connection.** The action's `getOutputStream()` is null, as under AGENDA, so it
+  must buffer its reply (`write`/`setBuffer`); one that streams unconditionally fails with
+  the NullPointerException as its result.
+- **Synchronous.** The CLI waits up to 300 s. Behind Cloudflare (prod) the request is cut
+  at about 100 s; the action still finishes on the server - check `vortex log`.
+- **Gateway required.** It needs a gateway with the `run` route; an older gateway refuses with
+  `NOT_EXPOSED`. Earlier versions of `object run` sent `tell agenda run`, which only reached
+  scheduled actions on AGENDA's list and did nothing, silently, for an ACTION.
 
 The 8.0 flags (`--show-schedule`, `--refresh-agenda`, `--flush-cache`, `--refresh-design`,
-`--run`) were removed in 8.1.
+`--run`) were removed in 8.1. `app refresh` was `app refresh-design` in 8.1.0; the old
+name still works.
 
 ### Local clones stay in sync
 
@@ -405,7 +440,7 @@ prints the command to re-sync (`vortex clone APP_ID -s SERVER`).
 | `object copy` | the target application's clone |
 | `keyword set` / `delete` | the clone's stored keywords |
 | `compile` | writes `zbin/`; `--upload` stores the uploaded blobs |
-| `execute --refresh-design` | none - prints that the clone is out of date |
+| `app refresh` / `execute refresh-design` | none - prints that the clone is out of date |
 | `app create` / `import` / `export`, all `db` commands | none |
 
 A clone stores the design objects, the application's details (with its description), its
@@ -526,6 +561,40 @@ vortex object get 7901 --app-id 62                     # the parsed schedule
   starts; if that lands between the command's read and write, the old `LastRun` is written
   back and the action may run one interval early.
 
+### The agenda
+
+AGENDA has no API beyond its console commands, so `vortex agenda` sends them through the same
+console route as `vortex execute` (the gateway's `POST console`, `GatewaySystem`, or the SOAP
+console without the gateway) and parses the text they answer.
+
+```
+vortex agenda -s dev                     # = agenda list
+vortex agenda list --app-id 9 -s dev
+vortex agenda run 7825 --app-id 60 -s dev [--param AppID=12] [--refresh] [--force]
+```
+
+- **`list`** - `tell agenda schedule`: every scheduled action AGENDA has **loaded**, by next
+  run (server time), with the waitlist and AGENDA's counts (running, waitlisted, scheduled,
+  max at once). An action with empty `Options` is loaded as *on demand only*. Not listed: an
+  action with `Schedule=N`, one in a disabled application or an application with scheduled
+  actions disabled, and one created or renamed since AGENDA's last refresh (every 15
+  minutes). AGENDA says how many actions are running, never which.
+- **`run`** - queues a SCHEDULED_ACTION: `tell agenda run /group/app.pma/Name[?&KEY=VALUE...]`.
+  It runs as the system session when one of AGENDA's slots is free; its result is only in
+  `vortex log`. AGENDA answers that command with nothing, whatever it did, so `run` checks
+  first and sends nothing when AGENDA would not run it:
+  - `NOT_ON_AGENDA` - the action has `Schedule=N` (give it a schedule first), or it is not on
+    the loaded list. `--refresh` sends `tell agenda refresh` and checks again (for an action
+    created or renamed in the last 15 minutes).
+  - `ALREADY_QUEUED` - it is already waitlisted; AGENDA would skip it.
+  - `PREFIX_COLLISION` - AGENDA matches the path by prefix and queues it once per matching
+    item, so `.../SyncAll` would also match an item `.../Sync` and run twice. `--force` sends
+    it anyway.
+  - `WRONG_TYPE` - not a SCHEDULED_ACTION (an ACTION is run with `vortex object run`).
+- A queued run moves the action's next scheduled run (AGENDA resets it), and it can't be
+  stopped from here (`vortex execute tell agenda stop /group/app.pma/Name` asks the action to
+  quit; it has to check for that itself).
+
 ### Keyword values and secrets
 
 Keywords are an application's live configuration, and in practice they hold credentials in

{vortex_cli-8.1.0 → vortex_cli-8.2.0}/pyproject.toml

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

{vortex_cli-8.1.0 → vortex_cli-8.2.0}/vortex/cli.py

@@ -562,6 +562,9 @@ _EXECUTE_SHORTCUTS_HELP = """\
 Shortcuts (each sends the exact string the server's addins match):
     flush-cache           | tell http cache flush ('tell http flush cache' does nothing)
     refresh-agenda        | tell agenda refresh: AGENDA rereads every schedule now
+    refresh-design APP_ID | tell agenda run /<webdesign_path>/RefreshDesign?&AppID=N:
+                          | rebuild the application's design from its template
+                          | (same as 'vortex app refresh APP_ID')
     schedule              | tell agenda schedule: every scheduled action and its next run
 
 Console commands:
@@ -576,7 +579,7 @@ def add_execute_parser(
         aliases=("ex",),
         help=(
             "Send a console command to the server (or a shortcut: flush-cache, "
-            "refresh-agenda, schedule)"
+            "refresh-agenda, refresh-design APP_ID, schedule)"
         ),
         description=_EXECUTE_SHORTCUTS_HELP + _EXECUTE_PARSER_DESCRIPTION,
         formatter_class=RawDescriptionHelpFormatter,