vortex-cli 4.20.0__tar.gz → 4.21.0__tar.gz

{vortex_cli-4.20.0 → vortex_cli-4.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vortex_cli
-Version: 4.20.0
+Version: 4.21.0
 Summary: Vortex CLI
 Author-email: Jordan Amos <jordan.amos@gmail.com>
 License: MIT License
@@ -121,7 +121,10 @@ For a full list of commands see `--help`.
 - `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.
+- `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 `javac`.
+- `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.
 
@@ -144,7 +147,7 @@ vortex new object
 # → pick app from locally cloned list
 # → pick design type
 # → enter name
-# → enter content type (resource only)
+# → enter content type (resource/documentation only)
 # → enter parent page, open action, save action (page only)
 # → preview and confirm
 
@@ -163,3 +166,45 @@ 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
 ```
+
+### Compiling Java Design Objects
+
+`vortex compile` (alias `build`) compiles an application's Java Design Objects into `zbin/`
+with a real `javac`, independent of the IDE's incremental build - real compile errors, a
+nonzero exit code on failure, and no stub class files. `javac` is found via `java_home` in the
+server config, then `$JAVA_HOME`, then `PATH` (`--javac PATH` to override), and `--release` is
+derived from the application's Java class version. It also warns when nested/inner/anonymous
+classes are produced, since these cannot be deployed as Design Objects.
+
+```
+vortex compile              # compile all locally cloned apps for the server
+vortex compile 13           # compile one app
+vortex compile 13 --upload  # also upload changed .class files
+```
+
+While `vortex watch` is running, `--upload` isn't needed - watch uploads new class files from
+`zbin/` automatically.
+
+### 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: a `CLAUDE.md` with Puakma ground rules for coding
+agents, 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.

{vortex_cli-4.20.0 → vortex_cli-4.21.0}/README.md

@@ -79,7 +79,10 @@ For a full list of commands see `--help`.
 - `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.
+- `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 `javac`.
+- `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.
 
@@ -102,7 +105,7 @@ vortex new object
 # → pick app from locally cloned list
 # → pick design type
 # → enter name
-# → enter content type (resource only)
+# → enter content type (resource/documentation only)
 # → enter parent page, open action, save action (page only)
 # → preview and confirm
 
@@ -121,3 +124,45 @@ 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
 ```
+
+### Compiling Java Design Objects
+
+`vortex compile` (alias `build`) compiles an application's Java Design Objects into `zbin/`
+with a real `javac`, independent of the IDE's incremental build - real compile errors, a
+nonzero exit code on failure, and no stub class files. `javac` is found via `java_home` in the
+server config, then `$JAVA_HOME`, then `PATH` (`--javac PATH` to override), and `--release` is
+derived from the application's Java class version. It also warns when nested/inner/anonymous
+classes are produced, since these cannot be deployed as Design Objects.
+
+```
+vortex compile              # compile all locally cloned apps for the server
+vortex compile 13           # compile one app
+vortex compile 13 --upload  # also upload changed .class files
+```
+
+While `vortex watch` is running, `--upload` isn't needed - watch uploads new class files from
+`zbin/` automatically.
+
+### 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: a `CLAUDE.md` with Puakma ground rules for coding
+agents, 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.

{vortex_cli-4.20.0 → vortex_cli-4.21.0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "vortex_cli"
-version = "4.20.0"
+version = "4.21.0"
 description = "Vortex CLI"
 requires-python = ">=3.10"
 readme = { file = "README.md", content-type = "text/markdown" }
@@ -32,7 +32,15 @@ classifiers = [
 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

{vortex_cli-4.20.0 → vortex_cli-4.21.0}/vortex/cli.py

@@ -32,7 +32,7 @@ _EXECUTE_PARSER_DESCRIPTION = """\
 """
 
 
-def _check_int_in_range(val: str, min_: int = 0, max_: int | None = 50) -> int:
+def _check_int_in_range(val: str, min_: int = 1, max_: int | None = 50) -> int:
     new_val = int(val)
     if new_val < min_ or (max_ is not None and new_val > max_):
         raise ArgumentTypeError(f"%s is not between {min_} and {max_}. " % val)
@@ -90,8 +90,9 @@ def validate_args(
 ) -> None:
     if args.command == "new":
         msg = None
-        is_update_mode = bool(getattr(args, "update_ids", None))
-        if args.subcommand == "object":
+        is_update_mode = getattr(args, "update_ids", None) is not None
+        if args.subcommand in ("object", "obj"):
+            update_missing_ids = is_update_mode and not args.update_ids
             missing_required_fields = not is_update_mode and not (
                 args.name and args.app_id and args.design_type
             )
@@ -114,7 +115,9 @@ def validate_args(
                 or args.parent_page
                 or args.content_type
             )
-            if missing_required_fields and not wizard_mode:
+            if update_missing_ids:
+                msg = "--update requires at least one Design Object ID"
+            elif missing_required_fields and not wizard_mode:
                 msg = "--name, --app-id, and --type are required unless using --update"
             elif missing_content_type:
                 msg = (
@@ -670,11 +673,129 @@ def add_db_parser(command_parser: _SubParsersAction[ArgumentParser]) -> Argument
         action="store_true",
         help="Set this flag when running queries for altering/updating the database",
     )
+    _add_server_option(db_parser)
     return db_parser
 
 
 def add_docs_parser(command_parser: _SubParsersAction[ArgumentParser]) -> None:
-    command_parser.add_parser("docs", help="Open the Tornado Server Blackbook")
+    docs_parser = command_parser.add_parser(
+        "docs", help="Open the Tornado Server Blackbook"
+    )
+    docs_parser.add_argument(
+        "--serve",
+        action="store_true",
+        help=(
+            "Serve the Blackbook v2 as a searchable local website "
+            "instead of opening the PDF"
+        ),
+    )
+    docs_parser.add_argument(
+        "--port",
+        type=int,
+        default=8477,
+        metavar="PORT",
+        help="The port to serve the docs on with --serve [%(default)s]",
+    )
+
+
+def add_schema_parser(command_parser: _SubParsersAction[ArgumentParser]) -> None:
+    schema_parser = command_parser.add_parser(
+        "schema",
+        help=(
+            "Manage the Puakma data dictionary (PMATABLE/ATTRIBUTE): record "
+            "design-time table/column definitions and print the DDL to run "
+            "by hand. Never executes DDL"
+        ),
+    )
+    schema_parser.add_argument(
+        "database", help="The database name whose dictionary to manage"
+    )
+    schema_mutex = schema_parser.add_mutually_exclusive_group(required=True)
+    schema_mutex.add_argument("--add-table", metavar="TABLE")
+    schema_mutex.add_argument(
+        "--delete-table",
+        metavar="TABLE",
+        help="Remove a table definition (does NOT drop the real table)",
+    )
+    schema_mutex.add_argument("--add-column", nargs=2, metavar=("TABLE", "COLUMN"))
+    schema_mutex.add_argument("--update-column", nargs=2, metavar=("TABLE", "COLUMN"))
+    schema_mutex.add_argument(
+        "--delete-column",
+        nargs=2,
+        metavar=("TABLE", "COLUMN"),
+        help="Remove a column definition (does NOT alter the real table)",
+    )
+    schema_mutex.add_argument(
+        "--ddl",
+        metavar="TABLE",
+        dest="ddl_table",
+        help="Print CREATE TABLE DDL generated from the dictionary definitions",
+    )
+    col_group = schema_parser.add_argument_group("Column Options")
+    col_group.add_argument("--type", dest="type_", metavar="SQL_TYPE")
+    col_group.add_argument("--size", metavar="N", help="e.g. 50 or '10,2'")
+    col_group.add_argument("--not-null", action="store_true")
+    col_group.add_argument("--pk", action="store_true")
+    col_group.add_argument("--auto-increment", action="store_true")
+    col_group.add_argument("--unique", action="store_true")
+    col_group.add_argument("--default", metavar="VALUE")
+    col_group.add_argument(
+        "--ref", metavar="TABLE.COLUMN", help="Foreign key reference"
+    )
+    col_group.add_argument("--description", metavar="TEXT")
+    col_group.add_argument("--position", type=int, metavar="N")
+    _add_server_option(schema_parser)
+
+
+def add_compile_parser(command_parser: _SubParsersAction[ArgumentParser]) -> None:
+    compile_parser = command_parser.add_parser(
+        "compile",
+        aliases=["build"],
+        help=(
+            "Compile an app's Java design elements into zbin/ with javac. "
+            "Real compile errors, no IDE error-stub classes"
+        ),
+    )
+    compile_parser.add_argument(
+        "app_ids",
+        nargs="*",
+        type=int,
+        metavar="APP_ID",
+        help=(
+            "App id(s) to compile. Default is all locally cloned apps " "for the server"
+        ),
+    )
+    compile_parser.add_argument(
+        "--upload",
+        "-u",
+        action="store_true",
+        help=(
+            "Upload changed .class files after a successful compile. "
+            "Not needed while 'vortex watch' is running - watch uploads "
+            "new class files automatically"
+        ),
+    )
+    compile_parser.add_argument(
+        "--javac",
+        metavar="PATH",
+        dest="javac_path",
+        help=(
+            "Path to javac. Default: <java_home>/bin/javac from the server "
+            "config, else $JAVA_HOME, else javac on PATH"
+        ),
+    )
+    _add_server_option(compile_parser)
+
+
+def add_agent_parser(command_parser: _SubParsersAction[ArgumentParser]) -> None:
+    command_parser.add_parser(
+        "agent",
+        help=(
+            "Generate agent/editor support files in the workspace "
+            "(CLAUDE.md, Puakma skills, code snippets). Existing files "
+            "are never overwritten"
+        ),
+    )
 
 
 def add_execute_parser(command_parser: _SubParsersAction[ArgumentParser]) -> None:

vortex_cli-4.21.0/vortex/commands/agent.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import logging
+
+from vortex.workspace import Workspace
+
+logger = logging.getLogger("vortex")
+
+
+def agent(workspace: Workspace) -> int:
+    """
+    Generates the agent/editor support files (CLAUDE.md, Puakma skills,
+    code snippets) in the workspace .vscode directory. Existing files are
+    never overwritten.
+    """
+    written, skipped = workspace.init_agent_files()
+    for path in written:
+        logger.info(f"Created '{path}'")
+    for path in skipped:
+        logger.debug(f"Skipped existing '{path}'")
+    if not written:
+        logger.info(f"All {len(skipped)} agent file(s) already exist. Nothing to do.")
+    else:
+        logger.info(
+            f"Created {len(written)} file(s), kept {len(skipped)} existing file(s)."
+        )
+    return 0

{vortex_cli-4.20.0 → vortex_cli-4.21.0}/vortex/commands/clone.py

@@ -77,7 +77,7 @@ 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:
+    if app_ele is None:
         raise ValueError(f"Application [{app_id}] does not exist")
 
     db_connections: list[DatabaseConnection] = []

vortex_cli-4.21.0/vortex/commands/compile.py

@@ -0,0 +1,208 @@
+from __future__ import annotations
+
+import asyncio
+import configparser
+import logging
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from vortex.models import DesignObject
+from vortex.models import DesignObjectAmbiguousError
+from vortex.models import DesignObjectNotFound
+from vortex.models import DesignType
+from vortex.models import PuakmaApplication
+from vortex.models import PuakmaServer
+from vortex.workspace import Workspace
+
+logger = logging.getLogger("vortex")
+
+
+def _find_javac(
+    workspace: Workspace, server: PuakmaServer, override: str | None
+) -> str | None:
+    if override:
+        if Path(override).is_file():
+            return override
+        return shutil.which(override)
+    config = configparser.ConfigParser()
+    config.read(workspace.server_config_file)
+    java_home = config.get(server.name, "java_home", fallback=None) or os.getenv(
+        "JAVA_HOME"
+    )
+    if java_home:
+        exe = "javac.exe" if sys.platform == "win32" else "javac"
+        candidate = Path(java_home) / "bin" / exe
+        if candidate.is_file():
+            return str(candidate)
+    return shutil.which("javac")
+
+
+def _build_classpath(workspace: Workspace, server: PuakmaServer, app_dir: Path) -> str:
+    import vortex
+
+    lib_dir = Path(vortex.__file__).parent / "lib"
+    entries = [str(jar) for jar in sorted(lib_dir.glob("*.jar"))]
+    entries.extend(str(jar) for jar in sorted((app_dir / "zlib").rglob("*.jar")))
+    config = configparser.ConfigParser()
+    config.read(workspace.server_config_file)
+    server_libs = config.get(server.name, "lib_path", fallback=None)
+    if server_libs:
+        entries.extend(p for p in server_libs.split(",") if p)
+    entries.append(str(app_dir / "zbin"))
+    return os.pathsep.join(entries)
+
+
+def _compile_app(
+    workspace: Workspace,
+    server: PuakmaServer,
+    app: PuakmaApplication,
+    javac: str,
+) -> tuple[int, list[Path]]:
+    """
+    Compiles an app's Java design sources into zbin/ with javac.
+    Returns (exit_code, compiled_class_files).
+    """
+    app_dir = workspace.path / app.path
+    sources = [
+        str(f)
+        for dir_name in DesignType.source_dirs()
+        for f in sorted((app_dir / dir_name).rglob("*.java"))
+    ]
+    if not sources:
+        logger.info(f"{app}: no Java sources to compile")
+        return 0, []
+
+    zbin = app_dir / "zbin"
+    zbin.mkdir(exist_ok=True)
+
+    cmd = [javac, "-d", str(zbin), "-cp", _build_classpath(workspace, server, app_dir)]
+    if app.java_class_version:
+        # Class file major version N == Java release N - 44 (61 -> 17)
+        cmd.extend(["--release", str(app.java_class_version[0] - 44)])
+    cmd.extend(sources)
+
+    logger.info(f"Compiling {len(sources)} source file(s) for {app}...")
+    result = subprocess.run(cmd, capture_output=True, text=True)
+    if result.stdout.strip():
+        print(result.stdout, end="")
+    if result.returncode != 0:
+        print(result.stderr, file=sys.stderr, end="")
+        logger.error(f"{app}: compilation FAILED")
+        return 1, []
+    if result.stderr.strip():
+        # javac warnings
+        print(result.stderr, file=sys.stderr, end="")
+
+    compiled = sorted(zbin.rglob("*.class"))
+    nested = [c for c in compiled if "$" in c.name]
+    if nested:
+        names = ", ".join(sorted({c.name for c in nested}))
+        logger.warning(
+            f"{app}: nested/inner/anonymous classes compiled ({names}) - "
+            "these CANNOT be deployed as design elements; refactor to "
+            "top-level SHARED_CODE classes"
+        )
+    logger.info(f"{app}: compilation OK")
+    return 0, compiled
+
+
+async def _aupload_classes(
+    workspace: Workspace,
+    server: PuakmaServer,
+    to_upload: list[tuple[PuakmaApplication, DesignObject]],
+) -> int:
+    ret = 0
+    async with server as s:
+        await s.server_designer.ainitiate_connection()
+        for _app, obj in to_upload:
+            ok = await obj.aupload(s.download_designer, upload_source=False)
+            ret |= 0 if ok else 1
+    for app in {app for app, _obj in to_upload}:
+        workspace.mkdir(app)
+    return ret
+
+
+def _collect_uploads(
+    app: PuakmaApplication, class_files: list[Path]
+) -> list[tuple[PuakmaApplication, DesignObject]]:
+    """
+    Matches compiled top-level classes to design objects, skipping classes
+    whose bytes already match the manifest's design data.
+    """
+    to_upload = []
+    for class_file in class_files:
+        if "$" in class_file.name:
+            continue
+        try:
+            _, obj = app.lookup_design_obj(class_file.stem)
+        except DesignObjectNotFound:
+            continue
+        except DesignObjectAmbiguousError as e:
+            logger.warning(f"Not uploading '{class_file.name}': {e}")
+            continue
+        if not obj.design_type.is_java_type or obj.is_jar_library:
+            continue
+        class_bytes = class_file.read_bytes()
+        try:
+            unchanged = obj.design_data == class_bytes
+        except Exception:
+            unchanged = False
+        if unchanged:
+            logger.debug(f"{obj.name}: unchanged, skipping upload")
+            continue
+        obj.design_data = class_bytes
+        to_upload.append((app, obj))
+    return to_upload
+
+
+def compile_(
+    workspace: Workspace,
+    server: PuakmaServer,
+    app_ids: list[int],
+    *,
+    upload: bool = False,
+    javac_path: str | None = None,
+) -> int:
+    javac = _find_javac(workspace, server, javac_path)
+    if not javac:
+        logger.error(
+            "javac not found. Set 'java_home' in the server config, "
+            "$JAVA_HOME, or pass --javac PATH"
+        )
+        return 1
+    logger.debug(f"Using javac: {javac}")
+
+    apps = workspace.listapps(server)
+    if app_ids:
+        apps = [app for app in apps if app.id in 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
+    if not apps:
+        logger.error("No locally cloned applications to compile")
+        return 1
+
+    ret = 0
+    compiled_per_app: list[tuple[PuakmaApplication, list[Path]]] = []
+    for app in apps:
+        app_ret, class_files = _compile_app(workspace, server, app, javac)
+        ret |= app_ret
+        if app_ret == 0 and class_files:
+            compiled_per_app.append((app, class_files))
+
+    if upload and ret == 0:
+        to_upload: list[tuple[PuakmaApplication, DesignObject]] = []
+        for app, class_files in compiled_per_app:
+            to_upload.extend(_collect_uploads(app, class_files))
+        if to_upload:
+            logger.info(f"Uploading {len(to_upload)} compiled class(es)...")
+            ret |= asyncio.run(_aupload_classes(workspace, server, to_upload))
+        else:
+            logger.info("All compiled classes match the server. Nothing to upload.")
+    elif upload and ret != 0:
+        logger.warning("Skipping upload because compilation failed")
+    return ret

{vortex_cli-4.20.0 → vortex_cli-4.21.0}/vortex/commands/db.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import logging
 import os
+import re
 import subprocess
 import sys
 import tempfile
@@ -159,14 +160,18 @@ def db(
             logger.error(f"No cloned applications with DB Connection ID '{conn_id}'")
             return 1
         if sql and not update:
-            sql = sql + f" LIMIT {limit_n_results}"
+            # Strip a trailing ';' and don't stack LIMITs so the appended
+            # clause can't create invalid SQL
+            sql = sql.strip().rstrip(";").rstrip()
+            if not re.search(r"\bLIMIT\b", sql, re.IGNORECASE):
+                sql = sql + f" LIMIT {limit_n_results}"
     else:
-        db_name = str(database).lower()
+        db_name = str(database).lower().replace("'", "''")
         update = False
         truncate_cols = False
         conn_id = server.puakma_db_conn_id
         if schema_table is not None:
-            sql = GET_SCHEMA_SQL % (db_name, schema_table)
+            sql = GET_SCHEMA_SQL % (db_name, schema_table.lower().replace("'", "''"))
         elif list_tables:
             sql = LIST_TABLES_SQL % db_name
 

vortex_cli-4.21.0/vortex/commands/docs.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import functools
+import http.server
+import logging
+import os
+import platform
+import shutil
+import subprocess
+import webbrowser
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger("vortex")
+
+DOCS_DIR = Path(os.path.dirname(__file__), "..", "docs").resolve()
+DEFAULT_PORT = 8477
+
+
+class _DocsRequestHandler(http.server.SimpleHTTPRequestHandler):
+    def log_message(self, fmt: str, *args: Any) -> None:
+        logger.debug(f"{self.address_string()} - {fmt % args}")
+
+
+def _serve(port: int) -> int:
+    handler = functools.partial(_DocsRequestHandler, directory=str(DOCS_DIR))
+    try:
+        server = http.server.ThreadingHTTPServer(("127.0.0.1", port), handler)
+    except OSError as e:
+        logger.error(f"Unable to start the docs server on port {port}: {e}")
+        return 1
+
+    url = f"http://127.0.0.1:{port}/"
+    logger.info(f"Serving the Blackbook at {url} (Ctrl+C to stop)")
+    webbrowser.open(url)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+    return 0
+
+
+def _open_pdf() -> int:
+    system = platform.system()
+    doc_path = DOCS_DIR / "Blackbook.pdf"
+
+    cmd = None
+    shell = False
+
+    if system == "Windows":
+        cmd = "start"
+        shell = True
+    # MacOS
+    elif system == "Darwin":
+        cmd = shutil.which("open")
+    elif system == "Linux":
+        cmd = shutil.which("xdg-open")
+
+    if cmd is None:
+        logger.error("Unable to determine default program to open file.")
+        return 1
+
+    try:
+        subprocess.Popen(
+            [cmd, str(doc_path)],
+            shell=shell,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+    except FileNotFoundError:
+        logger.error(f"Command '{cmd}' not found")
+        return 1
+
+    return 0
+
+
+def docs(serve: bool = False, port: int = DEFAULT_PORT) -> int:
+    if serve:
+        return _serve(port)
+    return _open_pdf()