vortex-cli 6.2.1__tar.gz → 6.3.0__tar.gz

{vortex_cli-6.2.1 → vortex_cli-6.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vortex_cli
-Version: 6.2.1
+Version: 6.3.0
 Summary: Vortex CLI
 Author-email: Jordan Amos <jordan.amos@gmail.com>
 License: MIT License
@@ -108,6 +108,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 6.3
+
+- **`vortex push` only uploads what changed.** On a `backend = gateway` server the push first
+  reads the server's element hashes and skips every file that already matches - a full-app push
+  that used to re-send (and journal) hundreds of identical files now sends the few that differ.
+  `--all` restores the old push-everything behaviour; `backend = soap` still pushes everything.
+- **Uploads run concurrently** - up to `--jobs N` elements at once (default 8; `-j 1` is the
+  old one-at-a-time push). A Java element's source and class still go in that order, and a
+  failed source stops that element's class from being uploaded over it.
+- **`push --name` prefers an exact match.** Previously `--name dashboard` also pushed a
+  `Dashboard` element; now the case-insensitive match only applies when nothing matches exactly.
+
 ## Upgrading to 6.0
 
 6.0 is additive - **the default behaviour is unchanged**. Every server keeps using the SOAP
@@ -163,7 +175,7 @@ For a full list of commands see `--help`.
 - `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.
+- `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. On a gateway server only files whose content differs from the server's are uploaded (compared by the server's element hashes; `--all` pushes everything), and elements upload concurrently (`--jobs N`, default 8) while each Java element's source always lands before its class. `--name` matches exactly first, case-insensitively only when nothing matches exactly.
 - `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).

{vortex_cli-6.2.1 → vortex_cli-6.3.0}/README.md

@@ -64,6 +64,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 6.3
+
+- **`vortex push` only uploads what changed.** On a `backend = gateway` server the push first
+  reads the server's element hashes and skips every file that already matches - a full-app push
+  that used to re-send (and journal) hundreds of identical files now sends the few that differ.
+  `--all` restores the old push-everything behaviour; `backend = soap` still pushes everything.
+- **Uploads run concurrently** - up to `--jobs N` elements at once (default 8; `-j 1` is the
+  old one-at-a-time push). A Java element's source and class still go in that order, and a
+  failed source stops that element's class from being uploaded over it.
+- **`push --name` prefers an exact match.** Previously `--name dashboard` also pushed a
+  `Dashboard` element; now the case-insensitive match only applies when nothing matches exactly.
+
 ## Upgrading to 6.0
 
 6.0 is additive - **the default behaviour is unchanged**. Every server keeps using the SOAP
@@ -119,7 +131,7 @@ For a full list of commands see `--help`.
 - `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.
+- `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. On a gateway server only files whose content differs from the server's are uploaded (compared by the server's element hashes; `--all` pushes everything), and elements upload concurrently (`--jobs N`, default 8) while each Java element's source always lands before its class. `--name` matches exactly first, case-insensitively only when nothing matches exactly.
 - `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).

{vortex_cli-6.2.1 → vortex_cli-6.3.0}/pyproject.toml

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

{vortex_cli-6.2.1 → vortex_cli-6.3.0}/vortex/cli.py

@@ -14,6 +14,7 @@ from typing import NamedTuple
 from vortex.commands.db import DEFAULT_LIMIT_N_RESULTS
 from vortex.commands.db import MAX_LIMIT_N_RESULTS
 from vortex.commands.db import MIN_LIMIT_N_RESULTS
+from vortex.commands.push import DEFAULT_JOBS as DEFAULT_PUSH_JOBS
 from vortex.models import DesignType
 from vortex.models import PuakmaApplication
 
@@ -718,7 +719,31 @@ def add_push_parser(command_parser: _SubParsersAction[ArgumentParser]) -> None:
         "-n",
         dest="name_filter",
         default=None,
-        help="Only push the design element with this name",
+        help=(
+            "Only push the design element with this name (an exact match "
+            "wins; case-insensitive only when nothing matches exactly)"
+        ),
+    )
+    push_parser.add_argument(
+        "--all",
+        "-a",
+        action="store_true",
+        help=(
+            "Push every local file, including ones whose content already "
+            "matches the server. By default (gateway backend) unchanged "
+            "files are skipped using the server's element hashes"
+        ),
+    )
+    push_parser.add_argument(
+        "--jobs",
+        "-j",
+        type=int,
+        default=DEFAULT_PUSH_JOBS,
+        metavar="N",
+        help=(
+            "Maximum elements uploaded concurrently "
+            f"(default {DEFAULT_PUSH_JOBS}; 1 uploads one at a time)"
+        ),
     )
     _add_server_option(push_parser)
 

vortex_cli-6.3.0/vortex/commands/push.py

@@ -0,0 +1,303 @@
+"""
+vortex push - upload local design files without a watch session.
+
+Two things keep a push fast:
+
+1. Only what changed is uploaded. On backend=gateway the server's
+   element inventory carries a SHA-1 per blob ('elements?hashes=1', the
+   same primitive 'vortex pull' diffs with), so an upload whose local
+   bytes already hash to what the server holds is skipped. A full-app
+   push that used to re-send every file (and journal every one of them)
+   now sends the handful that differ. '--all' restores the old
+   everything-goes behaviour; backend=soap has no hashes and always
+   pushes everything.
+2. Uploads run concurrently, bounded by '--jobs'. The per-upload cost is
+   almost entirely the gateway's own journal + write + rehash, not the
+   round trip, and the gateway handles parallel requests fine ('vortex
+   watch' has always uploaded a save batch concurrently). The one order
+   that matters is kept: the blobs of ONE element (a Java source and its
+   compiled class) go strictly source-then-class - the journal keys
+   entries by millisecond + element, and a class must never land
+   without its source.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import hashlib
+import logging
+from typing import Any
+
+from vortex.commands.watch import aupload_design_routed
+from vortex.gateway import GatewayError
+from vortex.gateway import GatewayUnavailable
+from vortex.models import DesignObject
+from vortex.models import DesignType
+from vortex.models import PuakmaApplication
+from vortex.models import PuakmaServer
+from vortex.util import confirm_protected
+from vortex.workspace import Workspace
+
+logger = logging.getLogger("vortex")
+
+# Concurrent uploads in flight. Measured against a real gateway: 20
+# concurrent requests complete in the time of two sequential ones, so
+# the ceiling is politeness to the server, not throughput
+DEFAULT_JOBS = 8
+# 'elements?hashes=1' reads every blob server-side - allow for big apps
+HASHES_TIMEOUT_SECONDS = 300
+
+# (element, upload_source): SOURCE when True, DATA when False
+Upload = tuple[DesignObject, bool]
+
+
+def _b64_sha1(b64_blob: str) -> str:
+    """The gateway's hash encoding (base64 of SHA-1) of a base64 blob"""
+    return base64.b64encode(hashlib.sha1(base64.b64decode(b64_blob)).digest()).decode()
+
+
+def _select(objs: list[DesignObject], name_filter: str | None) -> list[DesignObject]:
+    """
+    The elements '--name' refers to. An exact name wins outright: an
+    app can hold both 'Dashboard' (SHARED_CODE) and 'dashboard' (PAGE),
+    and asking for one must not push the other. Only when nothing
+    matches exactly is the name matched case-insensitively.
+    """
+    if not name_filter:
+        return objs
+    exact = [o for o in objs if o.name == name_filter]
+    if exact:
+        return exact
+    wanted = name_filter.casefold()
+    return [o for o in objs if o.name.casefold() == wanted]
+
+
+def _collect(
+    workspace: Workspace, app: PuakmaApplication, name_filter: str | None
+) -> tuple[list[Upload], bool]:
+    """
+    (object, upload_source) pairs for every design object with a local
+    file: SOURCE from .java/DOCUMENTATION files, DATA from compiled
+    zbin classes and from PAGE/RESOURCE files. An element can appear
+    twice (java source + compiled class), source first. An element whose
+    class references nested classes is refused ENTIRELY - pushing its
+    source without the class would leave the server running old
+    bytecode with new source attached (silent drift) - and the second
+    return value reports that a refusal happened so push can exit
+    non-zero.
+    """
+    uploads: list[Upload] = []
+    refused = False
+    for obj in _select(app.design_objects, name_filter):
+        if obj.is_jar_library:
+            continue
+        design_path = obj.design_path(workspace).path
+        upload_source = (
+            obj.design_type.is_java_type or obj.design_type == DesignType.DOCUMENTATION
+        )
+        if design_path.exists():
+            file_bytes = design_path.read_bytes()
+            if upload_source:
+                obj.design_source = file_bytes
+            else:
+                obj.design_data = file_bytes
+            uploads.append((obj, upload_source))
+        if obj.design_type.is_java_type:
+            class_file = workspace.path / app.path / "zbin" / f"{obj.name}.class"
+            if class_file.exists():
+                nested = sorted(
+                    c.name for c in class_file.parent.glob(f"{class_file.stem}$*.class")
+                )
+                if nested:
+                    logger.error(
+                        f"Not pushing '{obj.name}' at all: its class "
+                        f"references nested classes ({', '.join(nested)}) "
+                        "which are never uploaded and would fail on the "
+                        "server. Refactor them to top-level SHARED_CODE "
+                        "classes first"
+                    )
+                    uploads = [u for u in uploads if u[0] is not obj]
+                    refused = True
+                    continue
+                obj.design_data = class_file.read_bytes()
+                uploads.append((obj, False))
+    return uploads, refused
+
+
+def _drop_unchanged(
+    client: Any,
+    app: PuakmaApplication,
+    uploads: list[Upload],
+    timeout: int = HASHES_TIMEOUT_SECONDS,
+) -> tuple[list[Upload], int]:
+    """
+    The uploads whose bytes differ from what the server holds, and how
+    many were dropped as identical. One 'elements?hashes=1' request per
+    app. An element the server no longer has, or a blob it reports no
+    hash for (SQL NULL), is never dropped - the upload itself gives the
+    real answer. If the inventory can't be read the whole list is kept:
+    a push must never silently do less than it was asked to.
+    """
+    try:
+        reply = client.get_elements(app.id, hashes=True, timeout=timeout)
+        by_id = {int(e["id"]): e for e in reply["elements"]}
+    except (GatewayError, KeyError, TypeError, ValueError) as e:
+        logger.warning(
+            f"[{app}] Couldn't read the server's element hashes ({e}) - "
+            "pushing every local file"
+        )
+        return uploads, 0
+    kept: list[Upload] = []
+    dropped = 0
+    for obj, upload_source in uploads:
+        element = by_id.get(obj.id)
+        server_hash = (
+            element.get("sourceHash" if upload_source else "dataHash")
+            if element is not None
+            else None
+        )
+        local_b64 = obj._design_source if upload_source else obj._design_data
+        if server_hash and str(server_hash) == _b64_sha1(local_b64):
+            logger.debug(
+                f"[{app}] {'SOURCE' if upload_source else 'DATA'} of {obj} "
+                "already matches the server - skipped"
+            )
+            dropped += 1
+        else:
+            kept.append((obj, upload_source))
+    return kept, dropped
+
+
+def _chains(uploads: list[Upload]) -> list[list[Upload]]:
+    """
+    Uploads grouped per element, in their collected order (source before
+    class). Chains run concurrently with each other; within a chain the
+    uploads are strictly sequential.
+    """
+    by_element: dict[tuple[int, int], list[Upload]] = {}
+    for obj, upload_source in uploads:
+        by_element.setdefault((obj.app.id, obj.id), []).append((obj, upload_source))
+    return list(by_element.values())
+
+
+async def _apush(
+    server: PuakmaServer, uploads: list[Upload], jobs: int = DEFAULT_JOBS
+) -> int:
+    """
+    Upload everything, at most `jobs` elements in flight at once. A
+    failed blob stops its element's chain: a class is never uploaded
+    over a source that didn't make it (and vice versa), so an element
+    is either fully updated or left as it was - but one element's
+    failure never stops the others.
+
+    That last guarantee has to hold for a RAISED failure too, not just
+    a False one. aupload_design_routed turns a gateway refusal/outage
+    into False itself, but the webdesign and SOAP paths can still raise
+    (a SOAP fault, an unexpected transport error, the handshake being
+    rejected). A bare gather would abandon every other chain mid-flight
+    and then close the HTTP client out from under those in-flight
+    uploads on the way out of 'async with server', so exceptions are
+    collected and reported per element instead.
+    """
+    semaphore = asyncio.Semaphore(max(1, jobs))
+    chains = _chains(uploads)
+
+    async def run_chain(chain: list[Upload]) -> bool:
+        async with semaphore:
+            for obj, upload_source in chain:
+                if not await aupload_design_routed(server, obj, upload_source):
+                    return False
+            return True
+
+    async with server:
+        # No eager SOAP handshake: each upload routes itself and only
+        # the ones taking the SOAP path connect (aupload_design_routed)
+        results = await asyncio.gather(
+            *(run_chain(c) for c in chains), return_exceptions=True
+        )
+    ret = 0
+    for chain, result in zip(chains, results, strict=True):
+        if isinstance(result, BaseException):
+            if not isinstance(result, Exception):
+                # Ctrl-C / cancellation is not an upload failure
+                raise result
+            logger.error(
+                f"[{server.name}] Upload of {chain[0][0]} failed: "
+                f"{type(result).__name__}: {result}"
+            )
+            ret = 1
+        elif not result:
+            ret = 1
+    return ret
+
+
+def push(
+    workspace: Workspace,
+    server: PuakmaServer,
+    app_ids: list[int],
+    name_filter: str | None,
+    *,
+    push_all: bool = False,
+    jobs: int = DEFAULT_JOBS,
+    timeout: int = HASHES_TIMEOUT_SECONDS,
+) -> int:
+    """
+    Push local design files to the server without a watch session (idea
+    V2 - closes the 'created outside watch = empty server-side source'
+    gap). Uploads go via the agent gateway when negotiated (journaled,
+    deploy-confirmed, unchanged files skipped), otherwise SOAP.
+    """
+    # '-j 0' / '-j -1' mean one at a time, not zero uploads - clamp here
+    # so the count that is logged is the count that is used
+    jobs = max(1, jobs)
+    apps = [app for app in workspace.listapps(server) if app.id in set(app_ids)]
+    missing = set(app_ids) - {app.id for app in apps}
+    if missing:
+        logger.error(f"No locally cloned app(s) with id(s): {sorted(missing)}")
+        return 1
+
+    try:
+        client = server.negotiate_gateway()
+    except GatewayUnavailable as e:
+        # backend=gateway and no usable gateway: nothing is pushed
+        # (no SOAP fallback - the journal is the point of the route)
+        logger.error(f"[{server.name}] {e} - nothing pushed")
+        return 1
+
+    uploads: list[Upload] = []
+    any_refused = False
+    skipped = 0
+    for app in apps:
+        app_uploads, refused = _collect(workspace, app, name_filter)
+        any_refused = any_refused or refused
+        if app_uploads and client is not None and not push_all:
+            app_uploads, dropped = _drop_unchanged(client, app, app_uploads, timeout)
+            skipped += dropped
+        uploads.extend(app_uploads)
+    if not uploads:
+        if skipped:
+            logger.info(
+                f"Nothing to push: {skipped} upload(s) already match the "
+                "server (--all pushes them anyway)"
+            )
+            return 1 if any_refused else 0
+        logger.error("Nothing to push (no matching local design files)")
+        return 1
+
+    if not confirm_protected(server, f"push {len(uploads)} design upload(s)"):
+        return 1
+    unchanged = f", {skipped} unchanged skipped" if skipped else ""
+    logger.info(
+        f"Pushing {len(uploads)} design upload(s){unchanged} ({jobs} at a time)..."
+    )
+    with workspace.app_locks((app.host, app.id) for app in apps):
+        ret = asyncio.run(_apush(server, uploads, jobs))
+        if ret == 0:
+            # re-pickle the manifests so they keep tracking what the
+            # server holds - the baseline 'vortex pull' diffs against
+            for app in apps:
+                workspace.mkdir(app)
+    # A refused element (nested classes) is a failure even when every
+    # other upload succeeded - scripts and agents must see it
+    return 1 if any_refused else ret

{vortex_cli-6.2.1 → vortex_cli-6.3.0}/vortex/main.py

@@ -359,7 +359,14 @@ def main(argv: Sequence[str] | None = None) -> int:
         elif args.command == "agenda":
             return agenda(server, args.show_all)
         elif args.command == "push":
-            return push(workspace, server, args.app_ids, args.name_filter)
+            return push(
+                workspace,
+                server,
+                args.app_ids,
+                args.name_filter,
+                push_all=args.all,
+                jobs=args.jobs,
+            )
         elif args.command == "pull":
             return pull(
                 workspace,

{vortex_cli-6.2.1 → vortex_cli-6.3.0}/vortex_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vortex_cli
-Version: 6.2.1
+Version: 6.3.0
 Summary: Vortex CLI
 Author-email: Jordan Amos <jordan.amos@gmail.com>
 License: MIT License
@@ -108,6 +108,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 6.3
+
+- **`vortex push` only uploads what changed.** On a `backend = gateway` server the push first
+  reads the server's element hashes and skips every file that already matches - a full-app push
+  that used to re-send (and journal) hundreds of identical files now sends the few that differ.
+  `--all` restores the old push-everything behaviour; `backend = soap` still pushes everything.
+- **Uploads run concurrently** - up to `--jobs N` elements at once (default 8; `-j 1` is the
+  old one-at-a-time push). A Java element's source and class still go in that order, and a
+  failed source stops that element's class from being uploaded over it.
+- **`push --name` prefers an exact match.** Previously `--name dashboard` also pushed a
+  `Dashboard` element; now the case-insensitive match only applies when nothing matches exactly.
+
 ## Upgrading to 6.0
 
 6.0 is additive - **the default behaviour is unchanged**. Every server keeps using the SOAP
@@ -163,7 +175,7 @@ For a full list of commands see `--help`.
 - `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.
+- `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. On a gateway server only files whose content differs from the server's are uploaded (compared by the server's element hashes; `--all` pushes everything), and elements upload concurrently (`--jobs N`, default 8) while each Java element's source always lands before its class. `--name` matches exactly first, case-insensitively only when nothing matches exactly.
 - `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).

vortex_cli-6.2.1/vortex/commands/push.py

@@ -1,132 +0,0 @@
-from __future__ import annotations
-
-import asyncio
-import logging
-
-from vortex.commands.watch import aupload_design_routed
-from vortex.models import DesignObject
-from vortex.models import DesignType
-from vortex.models import PuakmaApplication
-from vortex.models import PuakmaServer
-from vortex.util import confirm_protected
-from vortex.workspace import Workspace
-
-logger = logging.getLogger("vortex")
-
-
-def _collect(
-    workspace: Workspace, app: PuakmaApplication, name_filter: str | None
-) -> tuple[list[tuple[DesignObject, bool]], bool]:
-    """
-    (object, upload_source) pairs for every design object with a local
-    file: SOURCE from .java/DOCUMENTATION files, DATA from compiled
-    zbin classes and from PAGE/RESOURCE files. An element can appear
-    twice (java source + compiled class). An element whose class
-    references nested classes is refused ENTIRELY - pushing its source
-    without the class would leave the server running old bytecode with
-    new source attached (silent drift) - and the second return value
-    reports that a refusal happened so push can exit non-zero.
-    """
-    uploads: list[tuple[DesignObject, bool]] = []
-    refused = False
-    for obj in app.design_objects:
-        if name_filter and obj.name.casefold() != name_filter.casefold():
-            continue
-        if obj.is_jar_library:
-            continue
-        design_path = obj.design_path(workspace).path
-        upload_source = (
-            obj.design_type.is_java_type or obj.design_type == DesignType.DOCUMENTATION
-        )
-        if design_path.exists():
-            file_bytes = design_path.read_bytes()
-            if upload_source:
-                obj.design_source = file_bytes
-            else:
-                obj.design_data = file_bytes
-            uploads.append((obj, upload_source))
-        if obj.design_type.is_java_type:
-            class_file = workspace.path / app.path / "zbin" / f"{obj.name}.class"
-            if class_file.exists():
-                nested = sorted(
-                    c.name for c in class_file.parent.glob(f"{class_file.stem}$*.class")
-                )
-                if nested:
-                    logger.error(
-                        f"Not pushing '{obj.name}' at all: its class "
-                        f"references nested classes ({', '.join(nested)}) "
-                        "which are never uploaded and would fail on the "
-                        "server. Refactor them to top-level SHARED_CODE "
-                        "classes first"
-                    )
-                    uploads = [u for u in uploads if u[0] is not obj]
-                    refused = True
-                    continue
-                obj.design_data = class_file.read_bytes()
-                uploads.append((obj, False))
-    return uploads, refused
-
-
-async def _apush(server: PuakmaServer, uploads: list[tuple[DesignObject, bool]]) -> int:
-    from vortex.gateway import GatewayUnavailable
-
-    ret = 0
-    async with server as s:
-        # No eager SOAP handshake: each upload routes itself and only
-        # the ones taking the SOAP path connect (aupload_design_routed).
-        # On a gateway server the acting identity may have no SOAP
-        # access at all
-        try:
-            await asyncio.to_thread(s.negotiate_gateway)
-        except GatewayUnavailable as e:
-            # backend=gateway and no usable gateway: nothing is pushed
-            # (no SOAP fallback - the journal is the point of the route)
-            logger.error(f"[{s.name}] {e} - nothing pushed")
-            return 1
-        for obj, upload_source in uploads:
-            ok = await aupload_design_routed(s, obj, upload_source)
-            ret |= 0 if ok else 1
-    return ret
-
-
-def push(
-    workspace: Workspace,
-    server: PuakmaServer,
-    app_ids: list[int],
-    name_filter: str | None,
-) -> int:
-    """
-    Push local design files to the server without a watch session (idea
-    V2 - closes the 'created outside watch = empty server-side source'
-    gap). Uploads go via the agent gateway when negotiated (journaled,
-    deploy-confirmed), otherwise SOAP.
-    """
-    apps = [app for app in workspace.listapps(server) if app.id in set(app_ids)]
-    missing = set(app_ids) - {app.id for app in apps}
-    if missing:
-        logger.error(f"No locally cloned app(s) with id(s): {sorted(missing)}")
-        return 1
-
-    uploads: list[tuple[DesignObject, bool]] = []
-    any_refused = False
-    for app in apps:
-        app_uploads, refused = _collect(workspace, app, name_filter)
-        uploads.extend(app_uploads)
-        any_refused = any_refused or refused
-    if not uploads:
-        logger.error("Nothing to push (no matching local design files)")
-        return 1
-
-    if not confirm_protected(server, f"push {len(uploads)} design upload(s)"):
-        return 1
-    logger.info(f"Pushing {len(uploads)} design upload(s)...")
-    with workspace.app_locks((app.host, app.id) for app in apps):
-        ret = asyncio.run(_apush(server, uploads))
-        if ret == 0:
-            # re-pickle the manifests so they keep tracking what the
-            # server holds - the baseline 'vortex pull' diffs against
-            for app in apps:
-                workspace.mkdir(app)
-    # A refused element (nested classes) is a failure even when every
-    # other upload succeeded - scripts and agents must see it
-    return 1 if any_refused else ret