vortex-cli 3.0.0__tar.gz

vortex_cli-3.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 jordanamos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vortex_cli-3.0.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.1
+Name: vortex_cli
+Version: 3.0.0
+Summary: Vortex CLI
+Home-page: https://github.com/jordanamos/vortex-cli
+Author: Jordan Amos
+Author-email: jordan.amos@gmail.com
+License: MIT
+Keywords: vortex cli
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx==0.24.1
+Requires-Dist: tabulate==0.9.0
+Requires-Dist: watchfiles==0.19.0
+
+# Vortex CLI
+
+Vortex CLI is a command line alternative to the [Puakma Vortex IDE](https://github.com/brendonupson/PuakmaVortex) that simplifies the process of developing Puakma Applications on a [Puakma Tornado Server](https://github.com/brendonupson/Puakma) using Visual Studio Code. It allows you to clone applications from the server to a local workspace, edit the files using Visual Studio Code, and automatically upload changes to the server as you work.
+
+Vortex CLI also comes pre-packaged with the necessary Puakma .jar files for development.
+
+#### Visual Studio Code and Extensions
+
+While it is possible to use without it, this software has been purposefully designed for use with [Visual Studio Code](https://github.com/microsoft/vscode) and the [Project Manager For Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-dependency) or the [Extension Pack For Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack) extension. This software leverages [Workspaces](https://code.visualstudio.com/docs/editor/workspaces) in Visual Studio Code and manages a `vortex.code-workspace` file within the workspace.
+
+## Installation
+
+1. Install the tool using pip.
+
+   ```
+   pip install git+https://github.com/jordanamos/vortex-cli.git
+   ```
+
+2. It is recommended to set the workspace you would like to work out of via the `VORTEX_WORKSPACE` environment variable.
+
+   On Unix:
+
+   ```
+   export VORTEX_WORKSPACE=/path/to/workspace
+   ```
+
+   Otherwise, Vortex CLI will use a default **'vortex-cli-workspace'** directory inside your home directory.
+
+3. Create a **vortex-server-config.ini** file in your workspace to define the server(s) you will be working with.
+
+   To create the config file and also your workspace directory (if they don't already exist) you can use the config command:
+
+   ```
+   vortex config --init
+   ```
+
+   Then run the config command without flags to conviniently check your workspace and server configuration:
+
+   ```
+   vortex config
+   ```
+
+   Further, you can print a sample config definition using the '--sample' flag:
+
+   ```
+   vortex config --sample
+   ```
+
+   In the vortex-server-config.ini file, you can define as many servers as you need, each with their own unique name. For example:
+
+   ```
+   [DEFAULT] ; This section is optional and only useful if you have multiple definitions
+   port = 80 ; Options provided under DEFAULT will be applied to all definitions if not provided
+   soap_path = system/SOAPDesigner.pma
+   default = server1 ; Useful when you have multiple definitions
+
+   [server1] ; This can be called whatever you want and can be specified when using the --server flag i.e. 'vortex --server server1 list'
+   host = example.com
+   port = 8080 ; we can overwrite the DEFAULT value
+   puakma_db_conn_id = 13
+   username = myuser ; Optional
+   password = mypassword ; Optional
+   ```
+
+4. Setup the [Visual Studio Code Workspace](https://code.visualstudio.com/docs/editor/workspaces) to use the same Java version as your server in /path/to/workspace/.vscode/vortex.code-workspace under "settings", for example:
+   ```
+   "java.configuration.runtimes": [
+      {
+         "default": true,
+         "name": "JavaSE-1.8",
+         "path": "/Library/Java/JavaVirtualMachines/temurin-8.jdk/Contents/Home"
+      }
+   ]
+   ```
+
+## Usage
+
+### List Puakma Applications
+
+To list the Puakma Applications available on the server, use the `list` command:
+
+```
+vortex list
+```
+
+This will display a table showing the ID, name, template, and inheritance of each Puakma Application.
+
+### Clone a Puakma Application
+
+To clone a Puakma Application to the local workspace, use the `clone` command:
+
+```
+vortex clone [<APP_ID>, ...]
+```
+
+Replace `<APP_ID>` with the ID(s) of the Puakma Application(s) you want to clone. The tool will clone the application(s) into the local workspace.
+
+### Open the workspace in Visual Studio Code
+
+To open the Vortex CLI workspace in Visual Studio Code, use the `code` command:
+
+```
+vortex code
+```
+
+### Watch the workspace for changes
+
+To watch the workspace containing cloned Puakma Applications and automatically upload changes to the server, use the `watch` command:
+
+```
+vortex watch
+```
+
+This will start watching the workspace for changes. As you make changes to the files in the directory, the tool will automatically upload the changes to the server.
+
+### Delete locally cloned Puakma Applications
+
+To delete the locally cloned Puakma Application directories in the workspace, use the `clean` command:
+
+```
+vortex clean
+```
+
+### Create Design Objects
+
+To create new design objects, use the `new` command:
+
+```
+vortex new [NAME, ...] --app-id <app_id> --type <design_type>
+```
+
+Specify more than one name to create multiple design objects of the same type for the specified application
+
+### Delete Design Objects
+
+To delete a design object, use the `delete` command:
+
+```
+vortex delete [DESIGN_OBJECT_ID, ...]
+```
+
+### Find cloned Design Objects
+
+To search for Design Objects by name use the `find` command:
+
+```
+vortex find <name> [options]
+```
+
+### Search the contents of cloned Design Objects
+
+To search for text patterns in Design Objects using a [Regular Expression](https://learn.microsoft.com/en-us/dotnet/standard/base-types/regular-expression-language-quick-reference) use the `grep` command:
+
+```
+vortex grep <pattern> [options]
+```

vortex_cli-3.0.0/README.md

@@ -0,0 +1,156 @@
+# Vortex CLI
+
+Vortex CLI is a command line alternative to the [Puakma Vortex IDE](https://github.com/brendonupson/PuakmaVortex) that simplifies the process of developing Puakma Applications on a [Puakma Tornado Server](https://github.com/brendonupson/Puakma) using Visual Studio Code. It allows you to clone applications from the server to a local workspace, edit the files using Visual Studio Code, and automatically upload changes to the server as you work.
+
+Vortex CLI also comes pre-packaged with the necessary Puakma .jar files for development.
+
+#### Visual Studio Code and Extensions
+
+While it is possible to use without it, this software has been purposefully designed for use with [Visual Studio Code](https://github.com/microsoft/vscode) and the [Project Manager For Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-dependency) or the [Extension Pack For Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack) extension. This software leverages [Workspaces](https://code.visualstudio.com/docs/editor/workspaces) in Visual Studio Code and manages a `vortex.code-workspace` file within the workspace.
+
+## Installation
+
+1. Install the tool using pip.
+
+   ```
+   pip install git+https://github.com/jordanamos/vortex-cli.git
+   ```
+
+2. It is recommended to set the workspace you would like to work out of via the `VORTEX_WORKSPACE` environment variable.
+
+   On Unix:
+
+   ```
+   export VORTEX_WORKSPACE=/path/to/workspace
+   ```
+
+   Otherwise, Vortex CLI will use a default **'vortex-cli-workspace'** directory inside your home directory.
+
+3. Create a **vortex-server-config.ini** file in your workspace to define the server(s) you will be working with.
+
+   To create the config file and also your workspace directory (if they don't already exist) you can use the config command:
+
+   ```
+   vortex config --init
+   ```
+
+   Then run the config command without flags to conviniently check your workspace and server configuration:
+
+   ```
+   vortex config
+   ```
+
+   Further, you can print a sample config definition using the '--sample' flag:
+
+   ```
+   vortex config --sample
+   ```
+
+   In the vortex-server-config.ini file, you can define as many servers as you need, each with their own unique name. For example:
+
+   ```
+   [DEFAULT] ; This section is optional and only useful if you have multiple definitions
+   port = 80 ; Options provided under DEFAULT will be applied to all definitions if not provided
+   soap_path = system/SOAPDesigner.pma
+   default = server1 ; Useful when you have multiple definitions
+
+   [server1] ; This can be called whatever you want and can be specified when using the --server flag i.e. 'vortex --server server1 list'
+   host = example.com
+   port = 8080 ; we can overwrite the DEFAULT value
+   puakma_db_conn_id = 13
+   username = myuser ; Optional
+   password = mypassword ; Optional
+   ```
+
+4. Setup the [Visual Studio Code Workspace](https://code.visualstudio.com/docs/editor/workspaces) to use the same Java version as your server in /path/to/workspace/.vscode/vortex.code-workspace under "settings", for example:
+   ```
+   "java.configuration.runtimes": [
+      {
+         "default": true,
+         "name": "JavaSE-1.8",
+         "path": "/Library/Java/JavaVirtualMachines/temurin-8.jdk/Contents/Home"
+      }
+   ]
+   ```
+
+## Usage
+
+### List Puakma Applications
+
+To list the Puakma Applications available on the server, use the `list` command:
+
+```
+vortex list
+```
+
+This will display a table showing the ID, name, template, and inheritance of each Puakma Application.
+
+### Clone a Puakma Application
+
+To clone a Puakma Application to the local workspace, use the `clone` command:
+
+```
+vortex clone [<APP_ID>, ...]
+```
+
+Replace `<APP_ID>` with the ID(s) of the Puakma Application(s) you want to clone. The tool will clone the application(s) into the local workspace.
+
+### Open the workspace in Visual Studio Code
+
+To open the Vortex CLI workspace in Visual Studio Code, use the `code` command:
+
+```
+vortex code
+```
+
+### Watch the workspace for changes
+
+To watch the workspace containing cloned Puakma Applications and automatically upload changes to the server, use the `watch` command:
+
+```
+vortex watch
+```
+
+This will start watching the workspace for changes. As you make changes to the files in the directory, the tool will automatically upload the changes to the server.
+
+### Delete locally cloned Puakma Applications
+
+To delete the locally cloned Puakma Application directories in the workspace, use the `clean` command:
+
+```
+vortex clean
+```
+
+### Create Design Objects
+
+To create new design objects, use the `new` command:
+
+```
+vortex new [NAME, ...] --app-id <app_id> --type <design_type>
+```
+
+Specify more than one name to create multiple design objects of the same type for the specified application
+
+### Delete Design Objects
+
+To delete a design object, use the `delete` command:
+
+```
+vortex delete [DESIGN_OBJECT_ID, ...]
+```
+
+### Find cloned Design Objects
+
+To search for Design Objects by name use the `find` command:
+
+```
+vortex find <name> [options]
+```
+
+### Search the contents of cloned Design Objects
+
+To search for text patterns in Design Objects using a [Regular Expression](https://learn.microsoft.com/en-us/dotnet/standard/base-types/regular-expression-language-quick-reference) use the `grep` command:
+
+```
+vortex grep <pattern> [options]
+```

vortex_cli-3.0.0/setup.cfg

@@ -0,0 +1,60 @@
+[metadata]
+name = vortex_cli
+version = 3.0.0
+description = Vortex CLI
+long_description = file: README.md
+long_description_content_type = text/markdown
+url = https://github.com/jordanamos/vortex-cli
+author = Jordan Amos
+author_email = jordan.amos@gmail.com
+license = MIT
+license_files = LICENSE
+classifiers = 
+	Development Status :: 2 - Pre-Alpha
+	Intended Audience :: Developers
+	License :: OSI Approved :: MIT License
+	Natural Language :: English
+	Programming Language :: Python
+	Programming Language :: Python :: 3
+	Programming Language :: Python :: 3 :: Only
+keywords = vortex cli
+
+[options]
+packages = find:
+install_requires = 
+	httpx==0.24.1
+	tabulate==0.9.0
+	watchfiles==0.19.0
+python_requires = >=3.10
+
+[options.packages.find]
+exclude = 
+	tests*
+	testing*
+
+[options.entry_points]
+console_scripts = 
+	vortex = vortex.__main__:main
+
+[options.package_data]
+vortex = 
+	puakma/**/*.jar
+
+[flake8]
+max-line-length = 88
+
+[mypy]
+check_untyped_defs = true
+disallow_any_generics = true
+disallow_incomplete_defs = true
+disallow_untyped_defs = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+
+[mypy-tests.*]
+disallow_untyped_defs = false
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

vortex_cli-3.0.0/setup.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from setuptools import setup
+
+setup()

vortex_cli-3.0.0/vortex/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from vortex.main import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

vortex_cli-3.0.0/vortex/colour.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from enum import Enum
+
+
+class Colour(Enum):
+    NORMAL = "\033[m"
+    RED = "\033[41m"
+    BOLD = "\033[1m"
+    GREEN = "\033[42m"
+    YELLOW = "\033[43;30m"
+
+    @staticmethod
+    def highlight(text: str, colour: Colour, replace_in: str | None = None) -> str:
+        highlighted_txt = f"{colour.value}{text}{Colour.NORMAL.value}"
+        if replace_in:
+            highlighted_txt = replace_in.replace(text, highlighted_txt)
+        return highlighted_txt

vortex_cli-3.0.0/vortex/commands/clean.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import logging
+import shutil
+
+from vortex.workspace import Workspace
+
+
+logger = logging.getLogger("vortex")
+
+
+def clean(workspace: Workspace) -> int:
+    app_dirs = workspace.listdir(strict=False)
+    ret = 0
+    if app_dirs:
+        with workspace.exclusive_lock():
+            for app_dir in app_dirs:
+                shutil.rmtree(app_dir)
+                logger.info(f"Deleted directory '{app_dir}'")
+            ret = workspace.update_vscode_settings()
+    return ret

vortex_cli-3.0.0/vortex/commands/clone.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+import asyncio
+import binascii
+import logging
+import xml.etree.ElementTree as ET
+import zlib
+from pathlib import Path
+from typing import Any
+
+from vortex import util
+from vortex.models import DesignObject
+from vortex.models import DesignType
+from vortex.models import JavaClassVersion
+from vortex.models import PuakmaApplication
+from vortex.models import PuakmaServer
+from vortex.spinner import Spinner
+from vortex.workspace import Workspace
+
+logger = logging.getLogger("vortex")
+
+
+def clone(
+    workspace: Workspace,
+    server: PuakmaServer,
+    app_ids: list[int],
+    *,
+    get_resources: bool = False,
+    open_urls: bool = False,
+    reclone: bool = False,
+) -> int:
+    if reclone:
+        app_ids.extend(app.id for app in workspace.listapps(server))
+
+    with (
+        workspace.exclusive_lock(),
+        Spinner(f"Cloning {app_ids}..."),
+    ):
+        return asyncio.run(
+            _aclone_apps(workspace, server, app_ids, get_resources, open_urls)
+        )
+
+
+async def _aclone_apps(
+    workspace: Workspace,
+    server: PuakmaServer,
+    app_ids: list[int],
+    get_resources: bool,
+    open_urls: bool,
+) -> int:
+    tasks = []
+    async with server as s:
+        await s.server_designer.ainitiate_connection()
+        logger.info(f"Connected to {s.host}")
+
+        for app_id in app_ids:
+            task = asyncio.create_task(_aclone_app(workspace, s, app_id, get_resources))
+            tasks.append(task)
+
+        ret = 0
+        for done in asyncio.as_completed(tasks):
+            try:
+                app, _ret = await done
+                if open_urls and app:
+                    util.open_app_urls(app)
+                ret |= _ret
+            except (KeyboardInterrupt, Exception) as e:
+                for task in tasks:
+                    task.cancel()
+                raise e
+            except asyncio.CancelledError:
+                logger.error("Operation Cancelled")
+                for task in tasks:
+                    task.cancel()
+                ret = 1
+                break
+        else:
+            ret |= workspace.update_vscode_settings()
+    return ret
+
+
+async def _aclone_app(
+    workspace: Workspace,
+    server: PuakmaServer,
+    app_id: int,
+    get_resources: bool,
+) -> tuple[PuakmaApplication | None, int]:
+    """Clone a Puakma Application into a newly created directory"""
+
+    logger.info(f"Cloning [{app_id}] from {server.host}...")
+
+    app_xml, _obj_rows = await asyncio.gather(
+        server.app_designer.aget_application_xml(app_id),
+        PuakmaApplication.afetch_design_objects(server, app_id, get_resources),
+    )
+
+    try:
+        app, app_ele = _parse_app_xml(server, app_xml, app_id)
+    except (ValueError, KeyError) as e:
+        logger.error(e)
+        return None, 1
+
+    eles = app_ele.findall("designElement", namespaces=None)
+    objs = _aparse_design_objs(_obj_rows, app)
+    _match_and_validate_design_objs(objs, eles)
+
+    app.design_objects = objs
+    app_dir = workspace.mkdir(app, True)
+    try:
+        logger.info(f"Saving {len(objs)} ({len(eles)}) Design Objects [{app_id}]...")
+        await asyncio.to_thread(_save_objs, workspace, objs)
+    except asyncio.CancelledError:
+        util.rmtree(app_dir)
+        return None, 1
+
+    logger.info(f"Successfully cloned {app} into '{app_dir.name}'")
+
+    return app, 0
+
+
+def _save_objs(workspace: Workspace, objs: list[DesignObject]) -> None:
+    for obj in objs:
+        obj.save(workspace)
+
+
+def _aparse_design_objs(
+    objs: list[dict[str, Any]], app: PuakmaApplication
+) -> list[DesignObject]:
+    ret: list[DesignObject] = []
+    for obj in objs:
+        design_type_id = int(obj["type"])
+        name = obj["name"]
+        id_ = int(obj["id"])
+        try:
+            type_ = DesignType(design_type_id)
+        except ValueError:
+            logger.debug(
+                f"Skipped Design Object '{name}' [{obj['id']}]: "
+                f"Invalid Design Type [{design_type_id}]"
+            )
+            continue
+        ret.append(
+            DesignObject(
+                id_,
+                name,
+                app,
+                type_,
+                obj["ctype"],
+                obj["data"],
+                obj["src"],
+            )
+        )
+    return ret
+
+
+def _parse_app_xml(
+    server: PuakmaServer, app_xml: ET.Element, app_id: int
+) -> tuple[PuakmaApplication, ET.Element]:
+    app_ele = app_xml.find("puakmaApplication", namespaces=None)
+    if not app_ele:
+        raise ValueError(f"Application [{app_id}] does not exist")
+
+    java_version_ele = app_xml.find('.//sysProp[@name="java.class.version"]')
+    if java_version_ele is None or java_version_ele.text is None:
+        raise ValueError("Java class version not specified")
+    major, minor = (int(v) for v in java_version_ele.text.split(".", maxsplit=1))
+    version: JavaClassVersion = (major, minor)
+    app = PuakmaApplication(
+        id=int(app_ele.attrib["id"]),
+        name=app_ele.attrib["name"],
+        group=app_ele.attrib["group"],
+        inherit_from=app_ele.attrib["inherit"],
+        template_name=app_ele.attrib["template"],
+        java_class_version=version,
+        host=server.host,
+    )
+    return app, app_ele
+
+
+def _validate_crc32_checksum(obj: DesignObject, ele: dict[str, str]) -> bool:
+    data = obj.design_source if obj.do_save_source else obj.design_data
+    crc32_xml_key = "sourceCrc32" if obj.do_save_source else "dataCrc32"
+    crc32_checksum = int(ele.get(crc32_xml_key, 0))
+    try:
+        return crc32_checksum == zlib.crc32(data)
+    except (TypeError, binascii.Error):
+        return False
+
+
+def _match_and_validate_design_objs(
+    design_objs: list[DesignObject],
+    design_elements: list[ET.Element],
+) -> None:
+    design_objs_eles = {int(ele.attrib["id"]): ele for ele in design_elements}
+    for obj in reversed(design_objs):
+        ele = design_objs_eles.get(obj.id)
+        if ele is not None:
+            obj.is_jar_library = ele.attrib.get("library", "false") == "true"
+
+            package = ele.attrib.get("package", None)
+            obj.package_dir = Path(*package.split(".")) if package else None
+
+            open_action_param_ele = ele.find('.//designParam[@name="OpenAction"]')
+            if open_action_param_ele is not None:
+                obj.open_action = open_action_param_ele.attrib["value"]
+
+            save_action_param_ele = ele.find('.//designParam[@name="SaveAction"]')
+            if save_action_param_ele is not None:
+                obj.save_action = save_action_param_ele.attrib["value"]
+
+            parent_page_param_ele = ele.find('.//designParam[@name="ParentPage"]')
+            if parent_page_param_ele is not None:
+                obj.parent_page = parent_page_param_ele.attrib["value"]
+
+        if ele is None or not _validate_crc32_checksum(obj, ele.attrib):
+            design_objs.remove(obj)
+            logger.warning(
+                f"Unable to validate Design Object {obj}. It will not be saved."
+            )