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

vortex_cli-5.0.0/PKG-INFO

@@ -0,0 +1,324 @@
+Metadata-Version: 2.4
+Name: vortex_cli
+Version: 5.0.0
+Summary: Vortex CLI
+Author-email: Jordan Amos <jordan.amos@gmail.com>
+License: 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.
+        
+Keywords: vortex,cli,puakma,tornado
+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
+Provides-Extra: keyring
+Requires-Dist: keyring; extra == "keyring"
+Dynamic: license-file
+
+# Vortex CLI
+
+[![Build Status](https://dev.azure.com/amostj/vortex-cli/_apis/build/status%2Fjordanamos.vortex-cli?branchName=main)](https://dev.azure.com/amostj/vortex-cli/_build/latest?definitionId=11&branchName=main)  [![PyPI version](https://badge.fury.io/py/vortex-cli.svg)](https://badge.fury.io/py/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 vortex-cli
+   ```
+
+2. It is recommended to set the workspace you would like to work out of via the `VORTEX_HOME` environment variable.
+
+   On Unix:
+
+   ```
+   export VORTEX_HOME=/path/to/workspace
+   ```
+
+   Otherwise, Vortex CLI will use a default **'vortex-cli-workspace'** directory inside your home directory.
+
+3. Run vortex with the `--init` flag to create your workspace (If it doesn't already exist) and the necessary config files:
+   ```
+   vortex --init
+   ```
+
+4. Define the servers you will be working with in the `servers.ini` file inside the `.config` directory within your workspace. You can quickly access this using the `code` command to view your workspace in VSCode.
+
+   ```
+   vortex code
+   ```
+
+   In the `servers.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 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
+   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')
+   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 5.0
+
+5.0 changes some defaults you may rely on:
+
+- **`resource_ext_only` is replaced by `clone_with_resources` - and the meaning flipped.**
+  Previously the extensions *restricted* what `--get-resources` cloned. Now resources with the
+  listed extensions are **always** cloned, and `--get-resources` clones every resource
+  unfiltered. Rename the key in `servers.ini` (vortex warns while the old key is present).
+- **`vortex watch` now watches every cloned app across all servers** and uploads each change to
+  the server it was cloned from. Use `--server` for the old single-server behaviour, and mark
+  production definitions `protected = true` so they are never watched by accident.
+- **`vortex compile` now uses the Eclipse compiler (ecj)** - the same compiler the VS Code Java
+  extension uses - downloaded once per workspace. `--javac PATH` forces javac. `compile
+  --upload` is now a full refresh (uploads every compiled class, not just changed ones).
+- `find`, `grep` and `vortex list --local` now search all cloned apps unless `--server` is
+  given, and ID-taking commands infer their server from local clones (see below).
+
+## Usage
+
+For a full list of commands see `--help`.
+
+### Command Overview
+
+- `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`).
+- `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.
+- `log`: View the server log.
+- `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.
+- `copy`: Copy a Design Object from one application to another.
+- `delete`: Delete Design Objects by ID.
+- `db`: Interact with Database Connections. Accepts `--server`/`-s` like other commands for one-off queries against another server.
+- `schema`: Manage the Puakma data dictionary (PMATABLE/ATTRIBUTE): record table/column definitions and print the DDL to run by hand. Never executes DDL.
+- `compile` (or `build`): Compile an application's Java Design Objects into `zbin/` using the Eclipse compiler (ecj).
+- `libs`: Show or refresh the per-server Java library cache (each server's `puakma.jar` and shared libraries, downloaded from the server itself).
+- `agent`: Generate agent/editor support files (CLAUDE.md, Puakma skills, code snippets) in the workspace.
+- `docs`: Open the Tornado Server Blackbook.
+- `execute`: Execute a command on the server.
+
+### Working with Multiple Servers
+
+Each section in `servers.ini` defines a server (hosts must be unique across
+sections). Cloned apps remember which server they came from, so you can work on
+apps from several servers at the same time:
+
+- `vortex watch` watches **every** cloned app and uploads each change to the
+  server it was cloned from. One terminal, all servers. Log lines are prefixed
+  with the server name (e.g. `[dev] Upload DATA of ...`). Use `--server` to
+  watch a single server only.
+- Commands that take IDs (`clone`, `export`, `compile`, `delete`, `copy`) work
+  out the server on their own: IDs can be qualified as `SERVER:ID`
+  (e.g. `vortex export dev:123`), and unqualified IDs are resolved against your
+  locally cloned apps. If an ID exists on more than one server, vortex stops
+  and asks rather than guessing.
+- `find`, `grep` and `vortex list --local` search across all cloned apps unless
+  `--server` is given.
+- `watch`, `clone` and `clean` take a workspace-wide lock: only one watch at
+  a time, and cloning or cleaning is refused while a watch is running (stop
+  the watch first - a clone under a running watch adds directories the
+  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.
+- 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
+  **window-scoped** - folder-level settings are ignored - so the global
+  workspace unions every server's jars (version clashes between servers are
+  possible there). For a guaranteed-correct classpath, open a single server's
+  own workspace with `vortex code -s <server>` (generated as
+  `.vscode/<server>.code-workspace`, containing only that server's apps and
+  exactly its jars).
+
+`vortex use <server>` still sets the default server for commands that have no
+IDs to infer from (`list`, `log`, `db`, `execute`, `new`):
+
+```
+vortex use production
+vortex list
+```
+
+#### Credentials
+
+`username`/`password` can be left out of `servers.ini`. Each server's
+credentials resolve in this order and are only requested when a command
+actually connects to that server:
+
+1. The system keyring - store with `vortex config --set-password -s <server>`
+   (requires `pip install keyring`)
+2. Per-server environment variables `VORTEX_USERNAME_<SERVER>` /
+   `VORTEX_PASSWORD_<SERVER>` (e.g. `VORTEX_PASSWORD_DEV`)
+3. `VORTEX_USERNAME` / `VORTEX_PASSWORD`
+4. An interactive prompt naming the server
+
+#### Protected Servers
+
+Set `protected = true` on a server definition (e.g. production) to make it
+hard to change by accident:
+
+- Write operations (`delete`, `copy`, `new`, `import`, `db --update`,
+  `execute`, `schema` changes, `compile --upload`) require the server name to
+  be typed back to continue. This is deliberately **not** bypassed by `--yes`.
+- `vortex watch` skips protected servers unless `--include-protected` is
+  given, so saving a file can never hot-deploy to production by accident.
+
+### Interactive Wizards
+
+Run `vortex new object` or `vortex new app` without any flags to launch a step-by-step wizard:
+
+```
+vortex new object
+# → pick app from locally cloned list
+# → pick design type
+# → enter name
+# → enter content type (resource/documentation only)
+# → enter parent page, open action, save action (page only)
+# → preview and confirm
+
+vortex new app
+# → enter name
+# → pick from existing groups or enter a new one
+# → enter description (optional)
+# → preview and confirm
+```
+
+### Skipping Confirmation Prompts
+
+Pass `--yes` (or `-y`) to skip Y/y confirmation prompts, useful for scripting:
+
+```
+vortex --yes delete 123 456
+vortex -y new object --name MyAction --app-id 10 --type action
+```
+
+Note: `--yes` never bypasses the typed confirmation for servers marked
+`protected = true`.
+
+### Compiling Java Design Objects
+
+`vortex compile` (alias `build`) compiles an application's Java Design Objects into `zbin/`
+with the **Eclipse compiler (ecj)** - the same compiler the VS Code Java extension uses,
+downloaded once per workspace into `config/.tools/`. It runs via the `java` from `java_home`
+in the server config, then `$JAVA_HOME`, then `PATH`; `--release` is derived from the
+application's Java class version. ecj matters because Tornado loads each class from its own
+design element: `'$'` **classes (`Foo$1.class`) are never uploaded to the server**, and unlike
+javac, ecj compiles a `switch` over an enum into the class itself rather than a synthetic
+`Foo$1.class`. Classes that still produce `$` files (genuine anonymous/inner classes) are
+reported and **excluded from upload** - they would throw `NoClassDefFoundError` on the server.
+If ecj can't be downloaded (offline), javac is used with a warning; `--javac PATH` forces
+javac explicitly.
+
+```
+vortex compile              # compile all locally cloned apps for the server
+vortex compile 13           # compile one app
+vortex compile 13 --upload  # also upload ALL compiled classes (full server refresh)
+```
+
+While `vortex watch` is running, `--upload` isn't needed: saving a Java source uploads the
+SOURCE, and the VS Code Java extension's incremental build (which **is** the Eclipse
+compiler, ecj - the same compiler `vortex compile` downloads) writes the class files into
+`zbin/`, where watch picks them up and uploads the DATA - always, even when the bytes are
+unchanged, so a source change is always paired with its class on the server. `'$'`
+nested-class files are never uploaded - a class compiled alongside `$` siblings is refused
+with an error since it would fail on the server.
+Use `vortex compile` for full-application rebuilds without the IDE.
+
+### Server-Provided Java Libraries
+
+Compilation and IDE IntelliSense need the Puakma framework jar and the server's shared
+libraries on the classpath. Instead of maintaining local copies, vortex downloads them from
+each server's `webdesign` application (the `vortex` API's `systemjar` and `libraries`
+endpoints) and caches them per server under `<workspace>/<host>/.lib/`:
+
+- The cache is filled automatically the first time it's needed - on `clone`, `watch` and
+  `compile` - and never re-downloaded unless you ask.
+- `vortex libs` shows what's cached for each server; `vortex libs --refresh` re-downloads
+  (add `-s <server>` for one server), e.g. after a server upgrade.
+- `javac` (via `vortex compile`) and each app folder's VS Code Java settings use the app's
+  own server's cached jars, so identical class names on different servers/versions never
+  cross-contaminate.
+- Servers whose `webdesign` app doesn't provide the `vortex` API yet fall back to the
+  `puakma.jar` bundled with vortex-cli plus any `lib_path` entries, with a warning.
+- `vortex clean` keeps each host's `.lib` cache so the jars don't need
+  re-downloading; pass `--include-libs` to remove them as well.
+
+### Managing the Data Dictionary
+
+`vortex schema` records design-time table and column definitions in the Puakma data
+dictionary (the PMATABLE/ATTRIBUTE tables, which also back `vortex db --schema`) and prints
+the matching DDL for you to run by hand. It never executes DDL, and deletes only remove
+dictionary rows - never real tables or columns.
+
+```
+vortex schema mydb --add-table invoice --description "Customer invoices"
+vortex schema mydb --add-column invoice invoice_id --type BIGINT --pk --auto-increment
+vortex schema mydb --add-column invoice total --type NUMERIC --size 10,2 --not-null
+vortex schema mydb --add-column invoice customer_id --type BIGINT --ref customer.customer_id
+vortex schema mydb --ddl invoice    # print CREATE TABLE from the dictionary
+```
+
+### Agent Support Files
+
+`vortex agent` copies bundled support files into the workspace `.vscode` directory so they are
+included in the generated code-workspace: an `AGENTS.md` with Puakma ground rules for coding
+agents (including pointers to the bundled Blackbook v2 architecture reference), a `CLAUDE.md`
+that points Claude Code at `AGENTS.md`, a `.claude/skills/` library covering Puakma development
+and the vortex workflow, and a `vortex.code-snippets` file with common Puakma Java/HTML
+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.
+
+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/README.md

@@ -0,0 +1,280 @@
+# Vortex CLI
+
+[![Build Status](https://dev.azure.com/amostj/vortex-cli/_apis/build/status%2Fjordanamos.vortex-cli?branchName=main)](https://dev.azure.com/amostj/vortex-cli/_build/latest?definitionId=11&branchName=main)  [![PyPI version](https://badge.fury.io/py/vortex-cli.svg)](https://badge.fury.io/py/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 vortex-cli
+   ```
+
+2. It is recommended to set the workspace you would like to work out of via the `VORTEX_HOME` environment variable.
+
+   On Unix:
+
+   ```
+   export VORTEX_HOME=/path/to/workspace
+   ```
+
+   Otherwise, Vortex CLI will use a default **'vortex-cli-workspace'** directory inside your home directory.
+
+3. Run vortex with the `--init` flag to create your workspace (If it doesn't already exist) and the necessary config files:
+   ```
+   vortex --init
+   ```
+
+4. Define the servers you will be working with in the `servers.ini` file inside the `.config` directory within your workspace. You can quickly access this using the `code` command to view your workspace in VSCode.
+
+   ```
+   vortex code
+   ```
+
+   In the `servers.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 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
+   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')
+   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 5.0
+
+5.0 changes some defaults you may rely on:
+
+- **`resource_ext_only` is replaced by `clone_with_resources` - and the meaning flipped.**
+  Previously the extensions *restricted* what `--get-resources` cloned. Now resources with the
+  listed extensions are **always** cloned, and `--get-resources` clones every resource
+  unfiltered. Rename the key in `servers.ini` (vortex warns while the old key is present).
+- **`vortex watch` now watches every cloned app across all servers** and uploads each change to
+  the server it was cloned from. Use `--server` for the old single-server behaviour, and mark
+  production definitions `protected = true` so they are never watched by accident.
+- **`vortex compile` now uses the Eclipse compiler (ecj)** - the same compiler the VS Code Java
+  extension uses - downloaded once per workspace. `--javac PATH` forces javac. `compile
+  --upload` is now a full refresh (uploads every compiled class, not just changed ones).
+- `find`, `grep` and `vortex list --local` now search all cloned apps unless `--server` is
+  given, and ID-taking commands infer their server from local clones (see below).
+
+## Usage
+
+For a full list of commands see `--help`.
+
+### Command Overview
+
+- `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`).
+- `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.
+- `log`: View the server log.
+- `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.
+- `copy`: Copy a Design Object from one application to another.
+- `delete`: Delete Design Objects by ID.
+- `db`: Interact with Database Connections. Accepts `--server`/`-s` like other commands for one-off queries against another server.
+- `schema`: Manage the Puakma data dictionary (PMATABLE/ATTRIBUTE): record table/column definitions and print the DDL to run by hand. Never executes DDL.
+- `compile` (or `build`): Compile an application's Java Design Objects into `zbin/` using the Eclipse compiler (ecj).
+- `libs`: Show or refresh the per-server Java library cache (each server's `puakma.jar` and shared libraries, downloaded from the server itself).
+- `agent`: Generate agent/editor support files (CLAUDE.md, Puakma skills, code snippets) in the workspace.
+- `docs`: Open the Tornado Server Blackbook.
+- `execute`: Execute a command on the server.
+
+### Working with Multiple Servers
+
+Each section in `servers.ini` defines a server (hosts must be unique across
+sections). Cloned apps remember which server they came from, so you can work on
+apps from several servers at the same time:
+
+- `vortex watch` watches **every** cloned app and uploads each change to the
+  server it was cloned from. One terminal, all servers. Log lines are prefixed
+  with the server name (e.g. `[dev] Upload DATA of ...`). Use `--server` to
+  watch a single server only.
+- Commands that take IDs (`clone`, `export`, `compile`, `delete`, `copy`) work
+  out the server on their own: IDs can be qualified as `SERVER:ID`
+  (e.g. `vortex export dev:123`), and unqualified IDs are resolved against your
+  locally cloned apps. If an ID exists on more than one server, vortex stops
+  and asks rather than guessing.
+- `find`, `grep` and `vortex list --local` search across all cloned apps unless
+  `--server` is given.
+- `watch`, `clone` and `clean` take a workspace-wide lock: only one watch at
+  a time, and cloning or cleaning is refused while a watch is running (stop
+  the watch first - a clone under a running watch adds directories the
+  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.
+- 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
+  **window-scoped** - folder-level settings are ignored - so the global
+  workspace unions every server's jars (version clashes between servers are
+  possible there). For a guaranteed-correct classpath, open a single server's
+  own workspace with `vortex code -s <server>` (generated as
+  `.vscode/<server>.code-workspace`, containing only that server's apps and
+  exactly its jars).
+
+`vortex use <server>` still sets the default server for commands that have no
+IDs to infer from (`list`, `log`, `db`, `execute`, `new`):
+
+```
+vortex use production
+vortex list
+```
+
+#### Credentials
+
+`username`/`password` can be left out of `servers.ini`. Each server's
+credentials resolve in this order and are only requested when a command
+actually connects to that server:
+
+1. The system keyring - store with `vortex config --set-password -s <server>`
+   (requires `pip install keyring`)
+2. Per-server environment variables `VORTEX_USERNAME_<SERVER>` /
+   `VORTEX_PASSWORD_<SERVER>` (e.g. `VORTEX_PASSWORD_DEV`)
+3. `VORTEX_USERNAME` / `VORTEX_PASSWORD`
+4. An interactive prompt naming the server
+
+#### Protected Servers
+
+Set `protected = true` on a server definition (e.g. production) to make it
+hard to change by accident:
+
+- Write operations (`delete`, `copy`, `new`, `import`, `db --update`,
+  `execute`, `schema` changes, `compile --upload`) require the server name to
+  be typed back to continue. This is deliberately **not** bypassed by `--yes`.
+- `vortex watch` skips protected servers unless `--include-protected` is
+  given, so saving a file can never hot-deploy to production by accident.
+
+### Interactive Wizards
+
+Run `vortex new object` or `vortex new app` without any flags to launch a step-by-step wizard:
+
+```
+vortex new object
+# → pick app from locally cloned list
+# → pick design type
+# → enter name
+# → enter content type (resource/documentation only)
+# → enter parent page, open action, save action (page only)
+# → preview and confirm
+
+vortex new app
+# → enter name
+# → pick from existing groups or enter a new one
+# → enter description (optional)
+# → preview and confirm
+```
+
+### Skipping Confirmation Prompts
+
+Pass `--yes` (or `-y`) to skip Y/y confirmation prompts, useful for scripting:
+
+```
+vortex --yes delete 123 456
+vortex -y new object --name MyAction --app-id 10 --type action
+```
+
+Note: `--yes` never bypasses the typed confirmation for servers marked
+`protected = true`.
+
+### Compiling Java Design Objects
+
+`vortex compile` (alias `build`) compiles an application's Java Design Objects into `zbin/`
+with the **Eclipse compiler (ecj)** - the same compiler the VS Code Java extension uses,
+downloaded once per workspace into `config/.tools/`. It runs via the `java` from `java_home`
+in the server config, then `$JAVA_HOME`, then `PATH`; `--release` is derived from the
+application's Java class version. ecj matters because Tornado loads each class from its own
+design element: `'$'` **classes (`Foo$1.class`) are never uploaded to the server**, and unlike
+javac, ecj compiles a `switch` over an enum into the class itself rather than a synthetic
+`Foo$1.class`. Classes that still produce `$` files (genuine anonymous/inner classes) are
+reported and **excluded from upload** - they would throw `NoClassDefFoundError` on the server.
+If ecj can't be downloaded (offline), javac is used with a warning; `--javac PATH` forces
+javac explicitly.
+
+```
+vortex compile              # compile all locally cloned apps for the server
+vortex compile 13           # compile one app
+vortex compile 13 --upload  # also upload ALL compiled classes (full server refresh)
+```
+
+While `vortex watch` is running, `--upload` isn't needed: saving a Java source uploads the
+SOURCE, and the VS Code Java extension's incremental build (which **is** the Eclipse
+compiler, ecj - the same compiler `vortex compile` downloads) writes the class files into
+`zbin/`, where watch picks them up and uploads the DATA - always, even when the bytes are
+unchanged, so a source change is always paired with its class on the server. `'$'`
+nested-class files are never uploaded - a class compiled alongside `$` siblings is refused
+with an error since it would fail on the server.
+Use `vortex compile` for full-application rebuilds without the IDE.
+
+### Server-Provided Java Libraries
+
+Compilation and IDE IntelliSense need the Puakma framework jar and the server's shared
+libraries on the classpath. Instead of maintaining local copies, vortex downloads them from
+each server's `webdesign` application (the `vortex` API's `systemjar` and `libraries`
+endpoints) and caches them per server under `<workspace>/<host>/.lib/`:
+
+- The cache is filled automatically the first time it's needed - on `clone`, `watch` and
+  `compile` - and never re-downloaded unless you ask.
+- `vortex libs` shows what's cached for each server; `vortex libs --refresh` re-downloads
+  (add `-s <server>` for one server), e.g. after a server upgrade.
+- `javac` (via `vortex compile`) and each app folder's VS Code Java settings use the app's
+  own server's cached jars, so identical class names on different servers/versions never
+  cross-contaminate.
+- Servers whose `webdesign` app doesn't provide the `vortex` API yet fall back to the
+  `puakma.jar` bundled with vortex-cli plus any `lib_path` entries, with a warning.
+- `vortex clean` keeps each host's `.lib` cache so the jars don't need
+  re-downloading; pass `--include-libs` to remove them as well.
+
+### Managing the Data Dictionary
+
+`vortex schema` records design-time table and column definitions in the Puakma data
+dictionary (the PMATABLE/ATTRIBUTE tables, which also back `vortex db --schema`) and prints
+the matching DDL for you to run by hand. It never executes DDL, and deletes only remove
+dictionary rows - never real tables or columns.
+
+```
+vortex schema mydb --add-table invoice --description "Customer invoices"
+vortex schema mydb --add-column invoice invoice_id --type BIGINT --pk --auto-increment
+vortex schema mydb --add-column invoice total --type NUMERIC --size 10,2 --not-null
+vortex schema mydb --add-column invoice customer_id --type BIGINT --ref customer.customer_id
+vortex schema mydb --ddl invoice    # print CREATE TABLE from the dictionary
+```
+
+### Agent Support Files
+
+`vortex agent` copies bundled support files into the workspace `.vscode` directory so they are
+included in the generated code-workspace: an `AGENTS.md` with Puakma ground rules for coding
+agents (including pointers to the bundled Blackbook v2 architecture reference), a `CLAUDE.md`
+that points Claude Code at `AGENTS.md`, a `.claude/skills/` library covering Puakma development
+and the vortex workflow, and a `vortex.code-snippets` file with common Puakma Java/HTML
+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.
+
+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-4.20.1 → vortex_cli-5.0.0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "vortex_cli"
-version = "4.20.1"
+version = "5.0.0"
 description = "Vortex CLI"
 requires-python = ">=3.10"
 readme = { file = "README.md", content-type = "text/markdown" }
@@ -28,11 +28,22 @@ classifiers = [
     "Programming Language :: Python :: 3 :: Only"
 ]
 
+[project.optional-dependencies]
+keyring = ["keyring"]
+
 [project.entry-points."console_scripts"]
 vortex = "vortex.__main__:main"
 
 [tool.setuptools.package-data]
-vortex = ["lib/puakma-6.0.40.jar", "docs/Blackbook.pdf"]
+vortex = [
+    "lib/puakma-6.0.40.jar",
+    "docs/Blackbook.pdf",
+    "docs/Blackbook v2.md",
+    "docs/index.html",
+    "docs/marked.min.js",
+    "templates/agent/*",
+    "templates/agent/skills/*/*",
+]
 
 [tool.mypy]
 check_untyped_defs = true
@@ -46,6 +57,10 @@ warn_unused_ignores = true
 module = ["tests.*", "testing.*"]
 disallow_untyped_defs = false
 
+[[tool.mypy.overrides]]
+module = ["keyring", "keyring.*"]
+ignore_missing_imports = true
+
 [tool.ruff]
 # Exclude a variety of commonly ignored directories.
 exclude = [