py-ib-controller 0.0.0__tar.gz → 0.1.2__tar.gz

{py_ib_controller-0.0.0 → py_ib_controller-0.1.2}/.github/workflows/ci.yml

@@ -5,6 +5,11 @@ on:
     branches: [master]
   pull_request:
   workflow_dispatch:
+  workflow_call:
+
+env:
+  JAVA_VERSION: "17"
+  JAVA_DISTRIBUTION: zulu
 
 jobs:
   check-build-test:
@@ -29,8 +34,8 @@ jobs:
       - name: Set up JDK
         uses: actions/setup-java@v6
         with:
-          distribution: zulu
-          java-version: "17"
+          distribution: ${{ env.JAVA_DISTRIBUTION }}
+          java-version: ${{ env.JAVA_VERSION }}
 
       - name: Build Java agent jar
         run: make build

py_ib_controller-0.1.2/.github/workflows/publish.yml

@@ -0,0 +1,148 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+env:
+  PYTHON_VERSION: "3.12"
+  JAVA_VERSION: "17"
+  JAVA_DISTRIBUTION: zulu
+
+jobs:
+  check:
+    uses: ./.github/workflows/ci.yml
+
+  build:
+    needs: check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout full history
+        uses: actions/checkout@v7
+        with:
+          # setuptools-scm derives the package version from git tags
+          # (pyproject.toml: dynamic = ["version"]); a shallow clone
+          # would silently produce a fallback/dev version.
+          fetch-depth: 0
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@v10.1.0
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Restore environment
+        run: uv sync --all-groups
+
+      - name: Set up JDK
+        uses: actions/setup-java@v6
+        with:
+          distribution: ${{ env.JAVA_DISTRIBUTION }}
+          java-version: ${{ env.JAVA_VERSION }}
+
+      - name: Build jar and Python distribution
+        run: make dist
+
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write  # trusted publishing to PyPI -- no API token in secrets
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v8
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Sign distributions with Sigstore, upload to GitHub Release
+    needs: publish-to-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # mandatory for making GitHub Releases
+      id-token: write  # mandatory for sigstore
+    steps:
+      - name: Checkout full history
+        uses: actions/checkout@v7
+        with:
+          # git-cliff needs the full commit/tag log to build the changelog
+          fetch-depth: 0
+
+      - name: Download all the dists
+        uses: actions/download-artifact@v8
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Generate checksums
+        run: sha256sum dist/* > dist/SHA256SUMS
+
+      - name: Sign the dists with Sigstore
+        uses: sigstore/gh-action-sigstore-python@v3.5.0
+        with:
+          inputs: >-
+            ./dist/*.tar.gz ./dist/*.whl
+
+      - name: Generate changelog
+        uses: orhun/git-cliff-action@v4
+        with:
+          # no cliff.toml -- git-cliff's built-in default config already
+          # groups Conventional Commits (feat/fix/docs/...) correctly
+          args: --latest --tag ${{ github.ref_name }} --strip header
+          output: CHANGELOG_release.md
+
+      - name: Assemble release notes
+        env:
+          TAG: ${{ github.ref_name }}
+          REPO: ${{ github.repository }}
+        run: |
+          PREV_TAG=$(git describe --tags --abbrev=0 "$TAG^" 2>/dev/null || true)
+          {
+            cat CHANGELOG_release.md
+            echo
+            echo "## Installation"
+            echo
+            echo "    pip install py-ib-controller==${TAG#v}"
+            echo
+            echo "## Verifying release artifacts"
+            echo
+            echo "Assets are signed with [Sigstore](https://www.sigstore.dev/). To verify:"
+            echo
+            echo "    pip install sigstore"
+            echo "    sigstore verify identity dist/*.whl dist/*.tar.gz \\"
+            echo "      --cert-identity https://github.com/$REPO/.github/workflows/publish.yml@refs/tags/$TAG \\"
+            echo "      --cert-oidc-issuer https://token.actions.githubusercontent.com"
+            echo
+            echo "\`SHA256SUMS\` is attached for checksum verification."
+            if [ -n "$PREV_TAG" ]; then
+              echo
+              echo "**Full Changelog**: https://github.com/$REPO/compare/$PREV_TAG...$TAG"
+            fi
+          } > notes.md
+
+      - name: Create GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: >-
+          gh release create '${{ github.ref_name }}'
+          --repo '${{ github.repository }}' --notes-file notes.md
+
+      - name: Upload artifacts and signatures to GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        # dist/ contains the built packages, SHA256SUMS, plus the
+        # sigstore-produced signatures and certificates.
+        run: >-
+          gh release upload '${{ github.ref_name }}' dist/**
+          --repo '${{ github.repository }}'

{py_ib_controller-0.0.0 → py_ib_controller-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py-ib-controller
-Version: 0.0.0
+Version: 0.1.2
 Summary: Login/launch controller for TWS and IBKR Gateway, via an in-process Java agent
 Author-email: gnzsnz <8376642+gnzsnz@users.noreply.github.com>
 License-Expression: Apache-2.0
@@ -28,18 +28,36 @@ Heavily inspired by [IBC](https://github.com/IbcAlpha/IBC) project, now archived
 
 ## What it does?
 
-- Finds ibgateway/TWS installation, JRE and launchs it.
+- Finds ibgateway/TWS installation, JRE and launch it.
 - Automates user/password entry, waits for MFA.
-- Automates ibgatewa/TWS settings.
+- Automates ibgateway/TWS settings.
 - Manages pop-ups and automatically accept.
-
 - Manages ibgateway/TWS restarts.
 
 It provides a "**declarative**" engine, so settings and pop-ups can be "declared" by configuration entries.
 
 ## How to use it
 
+To use `ibcontroller` the recommended way is to install with uv/pipx or pip:
+
 ```bash
+# install with uv/pipx
+uv tool install py-ib-controller
+
+# with pip
+uv pip install py-ib-controller
+```
+
+Give it a spin, `ib-controller run --dotenv=.env-paper --trading-mode=paper --program=gateway --tws-channel latest`
+
+https://github.com/user-attachments/assets/b97f7180-29d9-4e09-b32f-8be838dff0e2
+
+To build from source, this is the short version, for a detailed guide please check the [development guide](./docs/development.md).
+
+```bash
+# 0. Fetch the code
+git clone https://github.com/gnzsnz/ibcontroller.git
+cd ibcontroller
 # 1. Build the Java agent jar and install the package (editable, for a source checkout)
 make dist
 uv sync
@@ -47,11 +65,7 @@ uv sync
 # 2. Scaffold a starter config directory (platformdirs default, or $IBC_APP_DIR)
 uv run ibcontroller init
 
-# 3. Export IBC_USERID / IBC_PASSWORD (see Credentials below) -- the
-#    only settings actually required. Everything else in the base ibcontroller.toml
-#    is commented out and already safe to run as-is: trading_mode defaults to "paper",
-#    and tws_version is auto-detected from standard tws_path.
-
+# 3. Export IBC_USERID / IBC_PASSWORD or create an .env file (see Credentials below).
 # 4. Run it -- Ctrl-C for a graceful shutdown
 uv run ibcontroller run
 ```
@@ -61,8 +75,6 @@ uv run ibcontroller run
 run directly on a fresh install -- it will still fail with a clear error naming whichever
 setting is actually missing (in practice, just the two credential env vars).
 
-`ibcontroller version` prints the installed package version.
-
 ### CLI parameters
 
 You can use the following cli parameters:
@@ -138,7 +150,9 @@ environment variables, with precedence `defaults < TOML file < .env < environmen
 can be loaded from a `.env` file. Credentials are environment-variable-only and must
 never appear in the config file.
 
-A sample file with all settings is provided as an [example](./ibcontroller.env).
+A sample file with all environment settings is provided as an [example](./ibcontroller.env).
+In the same way a sample `.toml` file with all config is
+[available](./ibcontroller/data/ibcontroller.toml.example).
 
 `ibcontroller init` (or the first `ibcontroller run`) copies starter templates into the
 config directory: `ibcontroller.toml` (every key commented out -- safe to run as-is,
@@ -263,7 +277,7 @@ malformed value is logged and skipped rather than aborting the other one.
 
 - `cold_restart_time` -- `"HH:MM"`, 24-hour, local time. Every **Sunday** at this time,
   ibcontroller closes the instance tidily and relaunches with a full fresh login forcing the weekly
- reauth IBKR requires around Sunday 01:00 US/Eastern token invalidation.
+ re-auth IBKR requires around Sunday 01:00 US/Eastern token invalidation.
 - `closedown_at` -- `"HH:MM"` (every day) or `"<Weekday> HH:MM"` (one day a week,
   `Weekday` a full English name, `Monday`..`Sunday`). Closes the instance tidily at that
   time, with no relaunch -- you're responsible for restarting it yourself.

{py_ib_controller-0.0.0 → py_ib_controller-0.1.2}/README.md

@@ -6,18 +6,36 @@ Heavily inspired by [IBC](https://github.com/IbcAlpha/IBC) project, now archived
 
 ## What it does?
 
-- Finds ibgateway/TWS installation, JRE and launchs it.
+- Finds ibgateway/TWS installation, JRE and launch it.
 - Automates user/password entry, waits for MFA.
-- Automates ibgatewa/TWS settings.
+- Automates ibgateway/TWS settings.
 - Manages pop-ups and automatically accept.
-
 - Manages ibgateway/TWS restarts.
 
 It provides a "**declarative**" engine, so settings and pop-ups can be "declared" by configuration entries.
 
 ## How to use it
 
+To use `ibcontroller` the recommended way is to install with uv/pipx or pip:
+
 ```bash
+# install with uv/pipx
+uv tool install py-ib-controller
+
+# with pip
+uv pip install py-ib-controller
+```
+
+Give it a spin, `ib-controller run --dotenv=.env-paper --trading-mode=paper --program=gateway --tws-channel latest`
+
+https://github.com/user-attachments/assets/b97f7180-29d9-4e09-b32f-8be838dff0e2
+
+To build from source, this is the short version, for a detailed guide please check the [development guide](./docs/development.md).
+
+```bash
+# 0. Fetch the code
+git clone https://github.com/gnzsnz/ibcontroller.git
+cd ibcontroller
 # 1. Build the Java agent jar and install the package (editable, for a source checkout)
 make dist
 uv sync
@@ -25,11 +43,7 @@ uv sync
 # 2. Scaffold a starter config directory (platformdirs default, or $IBC_APP_DIR)
 uv run ibcontroller init
 
-# 3. Export IBC_USERID / IBC_PASSWORD (see Credentials below) -- the
-#    only settings actually required. Everything else in the base ibcontroller.toml
-#    is commented out and already safe to run as-is: trading_mode defaults to "paper",
-#    and tws_version is auto-detected from standard tws_path.
-
+# 3. Export IBC_USERID / IBC_PASSWORD or create an .env file (see Credentials below).
 # 4. Run it -- Ctrl-C for a graceful shutdown
 uv run ibcontroller run
 ```
@@ -39,8 +53,6 @@ uv run ibcontroller run
 run directly on a fresh install -- it will still fail with a clear error naming whichever
 setting is actually missing (in practice, just the two credential env vars).
 
-`ibcontroller version` prints the installed package version.
-
 ### CLI parameters
 
 You can use the following cli parameters:
@@ -116,7 +128,9 @@ environment variables, with precedence `defaults < TOML file < .env < environmen
 can be loaded from a `.env` file. Credentials are environment-variable-only and must
 never appear in the config file.
 
-A sample file with all settings is provided as an [example](./ibcontroller.env).
+A sample file with all environment settings is provided as an [example](./ibcontroller.env).
+In the same way a sample `.toml` file with all config is
+[available](./ibcontroller/data/ibcontroller.toml.example).
 
 `ibcontroller init` (or the first `ibcontroller run`) copies starter templates into the
 config directory: `ibcontroller.toml` (every key commented out -- safe to run as-is,
@@ -241,7 +255,7 @@ malformed value is logged and skipped rather than aborting the other one.
 
 - `cold_restart_time` -- `"HH:MM"`, 24-hour, local time. Every **Sunday** at this time,
   ibcontroller closes the instance tidily and relaunches with a full fresh login forcing the weekly
- reauth IBKR requires around Sunday 01:00 US/Eastern token invalidation.
+ re-auth IBKR requires around Sunday 01:00 US/Eastern token invalidation.
 - `closedown_at` -- `"HH:MM"` (every day) or `"<Weekday> HH:MM"` (one day a week,
   `Weekday` a full English name, `Monday`..`Sunday`). Closes the instance tidily at that
   time, with no relaunch -- you're responsible for restarting it yourself.

{py_ib_controller-0.0.0 → py_ib_controller-0.1.2}/docs/development.md

@@ -87,7 +87,7 @@ as it can be: `javac` + `jar`, wired through a small `Makefile`.
 
 ## TWS / IBKR Gateway itself
 
-Download from IBKR directly [gateway](`https://www.interactivebrokers.com/en/trading/ibgateway-latest.php`) or [TWS](https://www.interactivebrokers.com/en/trading/download-tws.php). Then install.
+Download from IBKR directly [gateway](https://www.interactivebrokers.com/en/trading/ibgateway-latest.php) or [TWS](https://www.interactivebrokers.com/en/trading/download-tws.php). Then install.
 
 After the first run, `ibcontroller` renames the gateway/TWS script. This is required to manage restarts.
 
@@ -123,3 +123,10 @@ Day-to-day cycle: `make build` after any agent-side change, `uv run pytest` for
 source .venv/bin/activate
 ibcontroller run --dotenv=.env-paper --trading-mode=paper --program=gateway
 ```
+
+## Architecture
+
+`ibcontroller` follows a layered architecture with separation of concerns between layers.
+Any contribution must follow this separation of concerns.
+
+![ibcontroller schematic architecture](Architecture.svg)

{py_ib_controller-0.0.0 → py_ib_controller-0.1.2}/ibcontroller/cli.py

@@ -198,7 +198,7 @@ def run(  # noqa: PLR0913, PLR0917 -- one typer.Option per Config field, not
 def version() -> None:
     """Print the installed ibcontroller version."""
     try:
-        typer.echo(_pkg_version("ibcontroller"))
+        typer.echo(_pkg_version("py-ib-controller"))
     except PackageNotFoundError:
         typer.echo("unknown (not installed)")
 

{py_ib_controller-0.0.0 → py_ib_controller-0.1.2}/ibcontroller/config.py

@@ -131,6 +131,19 @@ def _log_level_converter(raw: object) -> int:
     return _LOG_LEVELS[name]
 
 
+def _expand_user(raw: object) -> str:
+    """Expands `~` regardless of source (factory default, TOML file, env var, CLI) --
+    without this, a bare `Path(...)` downstream treats a literal `~` as a relative path
+    component and creates a `~` directory instead of expanding to the home directory
+    (gitea #57). Single point of truth for every path-typed Config field, so no
+    consumption site needs its own `.expanduser()` call."""
+    return str(Path(str(raw)).expanduser())
+
+
+def _optional_path_converter(raw: object) -> str | None:
+    return None if raw is None else _expand_user(raw)
+
+
 class TradingMode(StrEnum):
     LIVE = "live"
     PAPER = "paper"
@@ -208,7 +221,9 @@ class Config:
     # The IBKR settings file to load (if any) -- see `ibkr_settings.toml.example`.
     # Defaults to `None` (inert) until a user points `[settings] file` at a renamed
     # copy of the example file. See module docstring for why this is deliberate.
-    settings_file: str | None = None
+    settings_file: str | None = ts.option(
+        default=None, converter=_optional_path_converter
+    )
     # instance default: f"{program}-{trading_mode.value}".
     instance: str = "{program}-{trading_mode}"
     program: str = "gateway"  # "gateway" or "tws"
@@ -220,11 +235,13 @@ class Config:
     # installs (not a strict enum). Defaults to "stable", the safer pick when several
     # channels are installed side by side.
     tws_channel: str = "stable"
-    tws_path: str | None = None
+    tws_path: str | None = ts.option(default=None, converter=_optional_path_converter)
     # Where TWS/Gateway itself stores its settings (IBC's own TWS_SETTINGS_PATH) --
     # deliberately NOT the same as tws_path (the install location). None defaults,
     # per instance, in launcher.py's resolve_tws_settings_path.
-    tws_settings_path: str | None = None
+    tws_settings_path: str | None = ts.option(
+        default=None, converter=_optional_path_converter
+    )
     # IBC-key-compatible settings (file or env, never a secret).
     trading_mode: TradingMode = TradingMode.PAPER
     # IBC: ReadOnlyLogin -- loaded but not yet wired to any behavior.
@@ -280,7 +297,9 @@ class Config:
     # (DictLoader), so the config file's `log_dir` and the IBC_LOG_DIR env var
     # genuinely override it. See load_config for the loader order.
     trace_enabled: bool = False
-    log_dir: str = ts.option(factory=lambda: str(resolve_app_dirs()[1]))
+    log_dir: str = ts.option(
+        factory=lambda: str(resolve_app_dirs()[1]), converter=_expand_user
+    )
     # Logging level for ibcontroller's own log file (not the raw wire trace).
     # Was previously unannotated (`log_level = logging.INFO`), which meant attrs
     # never turned it into a real field at all -- not configurable, silently fixed

{py_ib_controller-0.0.0 → py_ib_controller-0.1.2}/ibcontroller/launcher.py

@@ -16,7 +16,6 @@ import asyncio
 import functools
 import logging
 import platform
-import plistlib
 import re
 from dataclasses import dataclass
 from pathlib import Path
@@ -95,7 +94,7 @@ def _os_name() -> str:
 
 def _resolve_tws_path(config: Config, os_name: str) -> Path:
     if config.tws_path:
-        return Path(config.tws_path).expanduser()
+        return Path(config.tws_path)
     return Path.home() / ("Applications" if os_name == "macos" else "Jts")
 
 
@@ -113,7 +112,7 @@ def resolve_tws_settings_path(config: Config) -> Path:
     running live and paper concurrently is this project's normal use case,
     not an edge case to opt into safety for."""
     if config.tws_settings_path:
-        return Path(config.tws_settings_path).expanduser()
+        return Path(config.tws_settings_path)
     return Path.home() / "Jts" / config.instance
 
 
@@ -311,11 +310,10 @@ def _version_sort_key(version: str) -> tuple[int, ...]:
 
 def _read_i4j_variable(install4j_dir: Path, name: str) -> str | None:
     """A plain install4j `<variable name="{name}" value="..." />` entry --
-    distinct from `_read_jxbrowser_key`'s own regex, which pulls a `-D` flag
-    out of the much larger `javaOptions` variable's own value blob (two
-    different shapes in the same `i4jparams.conf` file). Used for `channel`,
-    which each installed version carries its own real value for, not a fixed
-    label."""
+    distinct from `_read_i4j_vmoptions`'s own handling of the much larger
+    `javaOptions` variable's own value blob (two different shapes in the same
+    `i4jparams.conf` file). Used for `channel`, which each installed version
+    carries its own real value for, not a fixed label."""
     conf = install4j_dir / "i4jparams.conf"
     if not conf.is_file():
         return None
@@ -441,48 +439,17 @@ def _read_vmoptions_file(path: Path) -> list[str]:
     return options
 
 
-def _read_jxbrowser_key(install4j_dir: Path) -> str | None:
-    """Passkey (WebAuthn) 2FA renders in an embedded browser (JxBrowser),
-    which needs `-DjxBrowserKey=<license key>` to initialise at all. Read
-    dynamically since the key is version-specific."""
-    conf = install4j_dir / "i4jparams.conf"
-    if not conf.is_file():
-        return None
-    match = re.search(r"DjxBrowserKey=([^\"\s]+)", conf.read_text())
-    return match.group(1) if match else None
-
-
-def _read_macos_vmoptions(app_bundle: Path) -> list[str]:
-    """`--add-opens`/`--add-exports` (JPMS strong encapsulation) live in the
-    `.app` bundle's `Info.plist` (install4j's `JavaVM`/`VMOptionArray`), not
-    in `ibgateway.vmoptions`. Read live from the installed app, not
-    hardcoded, since it can change per version.
-
-    Takes the `.app` bundle's own path directly (not `program_path`): the
-    bundle may already have been renamed by `_prevent_native_restart`, so
-    re-deriving `f"{program_path.name}.app"` here would silently miss it on
-    every relaunch after the first."""
-    app_plist = app_bundle / "Contents" / "Info.plist"
-    if not app_plist.is_file():
-        return []
-    with app_plist.open("rb") as f:
-        data = plistlib.load(f)
-    raw_options = data.get("JavaVM", {}).get("VMOptionArray", [])
-    return [opt for opt in raw_options if "${" not in opt and not opt.startswith("-D")]
-
-
-def _read_linux_vmoptions(install4j_dir: Path) -> list[str]:
-    """`--add-opens`/`--add-exports` (JPMS strong encapsulation) live in
-    install4j's own `javaOptions` variable inside `i4jparams.conf` on Linux,
-    not in `tws.vmoptions`/`ibgateway.vmoptions`. Mirrors
-    `_read_macos_vmoptions`'s role for `Info.plist` on macOS, just a
-    different source file for the same install4j mechanism.
-
-    Unlike the macOS version, `-D` tokens are kept here rather than filtered:
-    on Linux this same variable is also the only place some installs carry
-    real `-D` fixes (e.g. Gateway's `-Djdk.xml.elementAttributeLimit`) and a
-    `-DjxBrowserKey`. A harmless duplicate of `_read_jxbrowser_key`'s own
-    value when both fire -- the JVM just takes the last one."""
+def _read_i4j_vmoptions(install4j_dir: Path) -> list[str]:
+    """`--add-opens`/`--add-exports` (JPMS strong encapsulation), the real
+    XML-parser `-D` fixes (e.g. Gateway's `-Djdk.xml.elementAttributeLimit`),
+    and `-DjxBrowserKey` all live in install4j's own `javaOptions` variable
+    inside `i4jparams.conf`, not in `tws.vmoptions`/`ibgateway.vmoptions` --
+    true on both Linux and macOS (checked directly against IBC's own
+    `ibcstart.sh`, which reads this same variable, from this same
+    `{program_path}/.install4j` location, on both platforms uniformly, and
+    never touches macOS's `Info.plist` at all). `-D` tokens are kept here
+    rather than filtered -- this is the only place some installs carry them,
+    so filtering would silently drop real options."""
     raw = _read_i4j_variable(install4j_dir, "javaOptions")
     if not raw:
         return []
@@ -501,9 +468,7 @@ def _prevent_native_restart(program_path: Path) -> Path:
     it back.
 
     Idempotent: a second call after the rename already happened is a no-op,
-    returning the same renamed path. Returns the `.app` bundle's current real
-    path either way, since `_read_macos_vmoptions` needs to read
-    `Info.plist` from wherever it actually lives now, renamed or not.
+    returning the same renamed path.
 
     macOS only, called only under `os_name == "macos"` in `build_launch_plan`
     -- see `_prevent_native_restart_linux` for the Linux equivalent, called
@@ -538,10 +503,10 @@ def _prevent_native_restart_linux(program_path: Path, script_name: str) -> Path:
 
     Idempotent, matching `_prevent_native_restart`: a second call after the
     rename already happened is a no-op, returning the same renamed path.
-    Unlike the macOS version, the return value doesn't need to be read back by
-    a vmoptions reader -- `_read_linux_vmoptions` reads from
-    `.install4j/i4jparams.conf`, which doesn't move when this script is
-    renamed -- so callers only need this for its side effect."""
+    The return value doesn't need to be read back by a vmoptions reader --
+    `_read_i4j_vmoptions` reads from `.install4j/i4jparams.conf`, which
+    doesn't move when this script is renamed -- so callers only need this
+    for its side effect."""
     original = program_path / script_name
     renamed = program_path / f"{script_name}-1"
     if renamed.exists():
@@ -624,17 +589,12 @@ def build_launch_plan(
     channel = _read_i4j_variable(install4j_dir, "channel") or config.tws_channel
     vm_options.append(f"-Dchannel={channel}")
 
-    jxbrowser_key = _read_jxbrowser_key(install4j_dir)
-    if jxbrowser_key:
-        vm_options.append(f"-DjxBrowserKey={jxbrowser_key}")
-
     if os_name == "macos":
-        app_bundle = _prevent_native_restart(program_path)
-        vm_options.extend(_read_macos_vmoptions(app_bundle))
+        _prevent_native_restart(program_path)
     else:
         script_name = "ibgateway" if resolved_program == "gateway" else "tws"
         _prevent_native_restart_linux(program_path, script_name)
-        vm_options.extend(_read_linux_vmoptions(install4j_dir))
+    vm_options.extend(_read_i4j_vmoptions(install4j_dir))
 
     # Agent-side logging (java.util.logging, AgentMain.configureLogging, 2026-09-08):
     # its own per-instance file under the same shared log dir Python uses, so the

{py_ib_controller-0.0.0 → py_ib_controller-0.1.2}/py_ib_controller.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: py-ib-controller
-Version: 0.0.0
+Version: 0.1.2
 Summary: Login/launch controller for TWS and IBKR Gateway, via an in-process Java agent
 Author-email: gnzsnz <8376642+gnzsnz@users.noreply.github.com>
 License-Expression: Apache-2.0
@@ -28,18 +28,36 @@ Heavily inspired by [IBC](https://github.com/IbcAlpha/IBC) project, now archived
 
 ## What it does?
 
-- Finds ibgateway/TWS installation, JRE and launchs it.
+- Finds ibgateway/TWS installation, JRE and launch it.
 - Automates user/password entry, waits for MFA.
-- Automates ibgatewa/TWS settings.
+- Automates ibgateway/TWS settings.
 - Manages pop-ups and automatically accept.
-
 - Manages ibgateway/TWS restarts.
 
 It provides a "**declarative**" engine, so settings and pop-ups can be "declared" by configuration entries.
 
 ## How to use it
 
+To use `ibcontroller` the recommended way is to install with uv/pipx or pip:
+
 ```bash
+# install with uv/pipx
+uv tool install py-ib-controller
+
+# with pip
+uv pip install py-ib-controller
+```
+
+Give it a spin, `ib-controller run --dotenv=.env-paper --trading-mode=paper --program=gateway --tws-channel latest`
+
+https://github.com/user-attachments/assets/b97f7180-29d9-4e09-b32f-8be838dff0e2
+
+To build from source, this is the short version, for a detailed guide please check the [development guide](./docs/development.md).
+
+```bash
+# 0. Fetch the code
+git clone https://github.com/gnzsnz/ibcontroller.git
+cd ibcontroller
 # 1. Build the Java agent jar and install the package (editable, for a source checkout)
 make dist
 uv sync
@@ -47,11 +65,7 @@ uv sync
 # 2. Scaffold a starter config directory (platformdirs default, or $IBC_APP_DIR)
 uv run ibcontroller init
 
-# 3. Export IBC_USERID / IBC_PASSWORD (see Credentials below) -- the
-#    only settings actually required. Everything else in the base ibcontroller.toml
-#    is commented out and already safe to run as-is: trading_mode defaults to "paper",
-#    and tws_version is auto-detected from standard tws_path.
-
+# 3. Export IBC_USERID / IBC_PASSWORD or create an .env file (see Credentials below).
 # 4. Run it -- Ctrl-C for a graceful shutdown
 uv run ibcontroller run
 ```
@@ -61,8 +75,6 @@ uv run ibcontroller run
 run directly on a fresh install -- it will still fail with a clear error naming whichever
 setting is actually missing (in practice, just the two credential env vars).
 
-`ibcontroller version` prints the installed package version.
-
 ### CLI parameters
 
 You can use the following cli parameters:
@@ -138,7 +150,9 @@ environment variables, with precedence `defaults < TOML file < .env < environmen
 can be loaded from a `.env` file. Credentials are environment-variable-only and must
 never appear in the config file.
 
-A sample file with all settings is provided as an [example](./ibcontroller.env).
+A sample file with all environment settings is provided as an [example](./ibcontroller.env).
+In the same way a sample `.toml` file with all config is
+[available](./ibcontroller/data/ibcontroller.toml.example).
 
 `ibcontroller init` (or the first `ibcontroller run`) copies starter templates into the
 config directory: `ibcontroller.toml` (every key commented out -- safe to run as-is,
@@ -263,7 +277,7 @@ malformed value is logged and skipped rather than aborting the other one.
 
 - `cold_restart_time` -- `"HH:MM"`, 24-hour, local time. Every **Sunday** at this time,
   ibcontroller closes the instance tidily and relaunches with a full fresh login forcing the weekly
- reauth IBKR requires around Sunday 01:00 US/Eastern token invalidation.
+ re-auth IBKR requires around Sunday 01:00 US/Eastern token invalidation.
 - `closedown_at` -- `"HH:MM"` (every day) or `"<Weekday> HH:MM"` (one day a week,
   `Weekday` a full English name, `Monday`..`Sunday`). Closes the instance tidily at that
   time, with no relaunch -- you're responsible for restarting it yourself.