feat(extensions): add QuickFIX engine and upgrade package management

quantDIY · quantDIY · commit 9fdf04972dba · 2026-01-31T11:38:41.000-05:00
- EXTENSION: Add `extensions/cpp/quickfix`
  - Integrates standard C++ QuickFIX engine (Rule 0).
  - Includes Python bindings via `python3-dev` linkage.
  - Implements static linking to ensure `_quickfix.so` is portable across execution nodes.
  - Includes `SKILL.md` with usage examples.

- CLI: Transform `quanuxctl` into a Package Manager
  - Add `upstream_repo` support to `extension.yaml`.
  - Add `quanuxctl upgradeable &lt;name&gt;`: Checks GitHub tags for updates.
  - Add `quanuxctl upgrade &lt;name&gt;`: Auto-upgrades to latest SemVer tag.
  - Add `quanuxctl install &lt;name&gt; -v &lt;version&gt;`: Supports version pinning.
  - Add `quanuxctl remove &lt;name&gt;`: clean uninstall.

- DOCS: Update Documentation
  - Update `extensions/SKILL.md` with package management standards.
  - Update `server/cli/README.md` with new commands.
diff --git a/extensions/SKILL.md b/extensions/SKILL.md
@@ -43,14 +43,24 @@ display_name: "Sierra Chart Connector"
 version: "0.0.1"
 runtime: "go" # or "node", "python" (Go preferred)
 command: "./dist/sierra-bridge" # Relative to extension dir
-permissions:
   - "market.data.read"
   - "strategy.execute"
 env:
   - "QUANUX_BRIDGE_KEY" # Injected by quanuxctl
+upstream_repo: "https://github.com/my/repo.git" # (Optional) Enable Package Management
 ```
 
-## 4. Communication Protocol
+## 4. Package Management (Lifecycle)
+
+Extensions can opt-in to managed upgrades by defining `upstream_repo` in `extension.yaml`.
+
+-   **Versioning**: `quanuxctl` will query `git ls-remote --tags` on the upstream repo.
+-   **Build Script**: `quanuxctl` passes `QUANUX_EXT_VERSION` environment variable to `build.sh`.
+    -   Your `build.sh` MUST prioritize this variable over hardcoded versions.
+    -   Example: `VERSION=${QUANUX_EXT_VERSION:-"v1.0.0"}`.
+-   **Commands**: This enables `quanuxctl upgrade`, `upgradeable`, and `install -v`.
+
+## 5. Communication Protocol
 
 ### Inbound (Core -> Extension)
 -   Extensions SHOULD expose an HTTP or gRPC server.
diff --git a/extensions/cpp/quickfix/SKILL.md b/extensions/cpp/quickfix/SKILL.md
@@ -0,0 +1,84 @@
+---
+name: quickfix_engine
+description: High-performance Financial Information eXchange (FIX) engine for electronic trading.
+---
+
+# QuickFIX Engine
+
+This extension provides the [QuickFIX](https://github.com/quickfix/quickfix) engine, compliant with **Rule 0 (Performance = C++)**.
+
+## Features
+-   **C++ Core**: Sub-millisecond latency for high-frequency trading.
+-   **Python Bindings**: Scriptable control for Python strategies.
+-   **Static Linking**: Portable execution across Execution Nodes.
+
+## Usage (Python Strategy)
+
+```python
+import quickfix as fix
+
+class Application(fix.Application):
+    def onCreate(self, sessionID):
+        print("Session created:", sessionID)
+    
+    def onLogon(self, sessionID):
+        print("Logon:", sessionID)
+
+    def onLogout(self, sessionID):
+        print("Logout:", sessionID)
+
+    def toAdmin(self, message, sessionID):
+        pass
+
+    def fromAdmin(self, message, sessionID):
+        pass
+
+    def toApp(self, message, sessionID):
+        pass
+
+    def fromApp(self, message, sessionID):
+        print("Received message:", message)
+
+# Configuration
+settings = fix.SessionSettings("config.ini")
+application = Application()
+storeFactory = fix.FileStoreFactory(settings)
+logFactory = fix.FileLogFactory(settings)
+initiator = fix.SocketInitiator(application, storeFactory, settings, logFactory)
+
+# Start
+initiator.start()
+# ... keep running ...
+initiator.stop()
+```
+
+## Usage (C++ Execution Node)
+The C++ SDK (headers and static libs) is installed in `extensions/cpp/quickfix/dist`.
+Link against `libquickfix.a` and include headers from `include/`.
+
+## Management
+
+**Install (Latest)**
+```bash
+quanuxctl install quickfix
+```
+
+**Install (Specific Version)**
+```bash
+quanuxctl install quickfix -v v1.14.0
+```
+
+**Check for Updates**
+```bash
+quanuxctl upgradeable quickfix
+```
+
+**Auto-Upgrade**
+```bash
+quanuxctl upgrade quickfix
+```
+
+**Uninstall**
+```bash
+quanuxctl remove quickfix
+```
diff --git a/extensions/cpp/quickfix/build.sh b/extensions/cpp/quickfix/build.sh
@@ -0,0 +1,99 @@
+#!/bin/bash
+set -e
+
+# Change directory to the script's location
+cd "$(dirname "$0")"
+
+# Allow version override from environment, default to v1.15.1
+QUICKFIX_VERSION=${QUANUX_EXT_VERSION:-"v1.15.1"}
+REPO_URL="https://github.com/quickfix/quickfix.git"
+INSTALL_PREFIX="$(pwd)/dist"
+
+echo "=========================================="
+echo "Building QuickFIX Extension ($QUICKFIX_VERSION)"
+echo "=========================================="
+
+# 1. Clone or Update
+if [ ! -d "source" ]; then
+    echo "Cloning QuickFIX from $REPO_URL..."
+    git clone --depth 1 --branch $QUICKFIX_VERSION $REPO_URL source
+else
+    echo "QuickFIX source already exists."
+fi
+
+# 2. Prepare Build Directory
+rm -rf build
+mkdir -p build
+cd build
+
+# 3. Configure CMake
+# - CMAKE_BUILD_TYPE=Release: Performance optimization (Rule 0)
+# - HAVE_PYTHON3=ON: Enable Python bindings
+# - BUILD_SHARED_LIBS=OFF: Static linking for portability
+# - CMAKE_INSTALL_PREFIX: Local install for C++ SDK
+# - CMAKE_POLICY_VERSION_MINIMUM=3.5: Fix for newer CMake versions dropping legacy support
+echo "Configuring CMake..."
+PYTHON_EXEC=$(which python3)
+
+cmake ../source \
+    -DCMAKE_BUILD_TYPE=Release \
+    -DHAVE_PYTHON3=ON \
+    -DPython3_EXECUTABLE="$PYTHON_EXEC" \
+    -DBUILD_SHARED_LIBS=OFF \
+    -DBUILD_TESTING=OFF \
+    -DCMAKE_INSTALL_PREFIX="$INSTALL_PREFIX" \
+    -DCMAKE_POLICY_VERSION_MINIMUM=3.5 \
+    -DCMAKE_SHARED_LINKER_FLAGS="-undefined dynamic_lookup"
+
+# 4. Build
+echo "Building..."
+make -j$(nproc 2>/dev/null || sysctl -n hw.ncpu)
+
+# 5. Install C++ SDK (Headers & Libs)
+echo "Installing C++ SDK to $INSTALL_PREFIX..."
+make install
+
+# 6. Install Python Bindings
+# QuickFIX CMake installs python package to site-packages of the target python.
+# Since we want it in the current venv, we might need a manual step if CMake doesn't handle venv detection perfectly.
+# Usually, cmake install with proper Python3_EXECUTABLE does the right thing.
+echo "Verifying Python installation..."
+# Check if the module is importable
+if $PYTHON_EXEC -c "import quickfix; print('QuickFIX imported successfully')" 2>/dev/null; then
+    echo "Python bindings verified."
+else
+    echo "WARNING: Python bindings might not be in the path. Checking build artifacts..."
+    # Manual install fallback if needed (copying .so/.py to site-packages)
+    # But let's trust CMake install first.
+    # If using local install prefix, CMake creates lib/pythonX/site-packages
+    # We may need to copy that to the venv or add to PYTHONPATH.
+    
+    # Heuristic: Copy from dist/lib/python*/site-packages to venv
+    SITE_PACKAGES=$($PYTHON_EXEC -c "import site; print(site.getsitepackages()[0])")
+    echo "Deploying to $SITE_PACKAGES..."
+    
+    # Try to find the built python module in dist
+    FOUND_PKG=$(find "$INSTALL_PREFIX/lib" -name "quickfix.py" | head -n 1)
+    if [ -n "$FOUND_PKG" ]; then
+        PKG_DIR=$(dirname "$FOUND_PKG")
+        cp -v "$PKG_DIR"/* "$SITE_PACKAGES/"
+        cp -v "$PKG_DIR"/_quickfix*.so "$SITE_PACKAGES/" 2>/dev/null || true
+        cp -v "$PKG_DIR"/_quickfix*.dylib "$SITE_PACKAGES/" 2>/dev/null || true # MacOS
+        cp -v "$PKG_DIR"/_quickfix.dylib "$SITE_PACKAGES/_quickfix.so" 2>/dev/null || true # MacOS Rename
+        
+        # Dependency Fix: Copy libquickfix.dylib from dist/lib to site-packages
+        cp -v "$INSTALL_PREFIX/lib"/libquickfix*.dylib "$SITE_PACKAGES/"
+        
+        # RPATH Fix (MacOS): Tell _quickfix.so to look for libquickfix in the same directory
+        install_name_tool -change "@rpath/libquickfix.16.dylib" "@loader_path/libquickfix.16.dylib" "$SITE_PACKAGES/_quickfix.so" || true
+        
+        echo "Manually deployed Python bindings with RPATH fix."
+    else
+        echo "Could not find built python bindings in dist. You may need to set PYTHONPATH manually."
+    fi
+fi
+
+echo "=========================================="
+echo "QuickFIX Build Complete"
+echo "C++ SDK: $INSTALL_PREFIX"
+echo "=========================================="
diff --git a/extensions/cpp/quickfix/extension.yaml b/extensions/cpp/quickfix/extension.yaml
@@ -0,0 +1,13 @@
+name: quickfix
+display_name: QuickFIX Engine
+version: 1.15.1
+runtime: cpp
+description: "High-performance C++ FIX engine with Python bindings. Compliant with Rule 0 (Performance = C++)."
+upstream_repo: "https://github.com/quickfix/quickfix.git"
+command: "scripts/test_import.py" # Placeholder for testing
+env:
+  - FIX_CONFIG_PATH
+dependencies:
+  - cmake
+  - g++
+  - python3-dev
diff --git a/extensions/cpp/quickfix/source b/extensions/cpp/quickfix/source
@@ -0,0 +1 @@
+Subproject commit 6908dc8c1084eeb7af7f322d35216e9965684489
diff --git a/server/cli/README.md b/server/cli/README.md
@@ -15,6 +15,15 @@ A unified developer CLI for managing the QuanuX organism.
 *   `quanuxctl skills list`: View available AI skills.
 *   `quanuxctl module remove <name>`: Uninstall a core subsystem.
 
+## Extension Management (New)
+
+Manage extensions like packages (`npm` style):
+
+*   **Install**: `quanuxctl install quickfix` (or `install <name> -v <version>`)
+*   **Upgrade**: `quanuxctl upgrade <name>` (Auto-pulls latest GitHub tag)
+*   **Check Updates**: `quanuxctl upgradeable <name>`
+*   **Remove**: `quanuxctl remove <name>`
+
 ## Extending
 
 See `SKILL.md` for AI agent instructions on adding new command groups.
diff --git a/server/cli/src/quanuxctl/commands/extensions.py b/server/cli/src/quanuxctl/commands/extensions.py
@@ -336,8 +336,8 @@ def run_extension(name: str):
         console.print(f"[red]Error running extension: {e}[/red]")
 
 @app.command("install")
-def install_extension(name: str):
-    """Build/Install the extension (runs build.sh)."""
+def install_extension(name: str, version: str = typer.Option(None, "--version", "-v")):
+    """Build/Install the extension (runs build.sh). Use -v to specify version."""
     ext_path = find_extension_path(name)
     if not ext_path:
         console.print(f"[red]Extension '{name}' not found.[/red]")
@@ -346,10 +346,17 @@ def install_extension(name: str):
     build_script = (ext_path / "build.sh").resolve()
     if build_script.exists():
         console.print(f"[green]Building {name}... from {ext_path}[/green]")
+        
+        # Pass version override if specified
+        env = os.environ.copy()
+        if version:
+            console.print(f"[bold]Target Version: {version}[/bold]")
+            env["QUANUX_EXT_VERSION"] = version
+
         try:
             # Ensure executable
             os.chmod(build_script, 0o755)
-            subprocess.run([str(build_script)], cwd=ext_path.resolve(), check=True)
+            subprocess.run([str(build_script)], cwd=ext_path.resolve(), env=env, check=True)
             console.print(f"[bold green]✓ Build successful[/bold green]")
         except subprocess.CalledProcessError:
             console.print(f"[red]Build failed for {name}[/red]")
@@ -366,6 +373,80 @@ def install_extension(name: str):
         except subprocess.CalledProcessError:
              console.print(f"[red]Failed to install requirements[/red]")
 
+@app.command("upgradeable")
+def upgradeable(name: str):
+    """Check for available updates (compares installed version vs upstream tags)."""
+    manifest = load_manifest(name)
+    if not manifest:
+        console.print(f"[red]Extension '{name}' not found.[/red]")
+        return
+
+    upstream = manifest.get("upstream_repo")
+    current_version = manifest.get("version", "unknown")
+    
+    if not upstream:
+        console.print(f"[yellow]No upstream_repo defined for {name}. Cannot check for updates.[/yellow]")
+        return
+        
+    console.print(f"Current Version: [cyan]{current_version}[/cyan]")
+    console.print(f"Fetching tags from {upstream}...")
+    
+    try:
+        # Fetch tags via git ls-remote, sort by version
+        result = subprocess.run(
+            ["git", "ls-remote", "--tags", "--refs", "--sort=-v:refname", upstream],
+            capture_output=True, text=True, check=True
+        )
+        # Parse tags (refs/tags/dest/v1.2.3 -> v1.2.3)
+        tags = [line.split("/")[-1] for line in result.stdout.splitlines() if line.strip()]
+        
+        # Simple heuristic: filter tags that look like versions (vX.Y.Z or X.Y.Z)
+        # and take the top 5
+        versions = [t for t in tags if "v" in t or "." in t][:5]
+        
+        console.print("\n[bold]Available Versions (Top 5):[/bold]")
+        for v in versions:
+            if v == current_version or v == f"v{current_version}":
+                 console.print(f"  [green]{v} (Installed)[/green]")
+            else:
+                 console.print(f"  {v}")
+                 
+    except subprocess.CalledProcessError as e:
+        console.print(f"[red]Failed to fetch tags: {e}[/red]")
+
+@app.command("upgrade")
+def upgrade(name: str):
+    """Auto-upgrade to the latest version found upstream."""
+    manifest = load_manifest(name)
+    if not manifest: 
+        console.print(f"[red]Extension '{name}' not found.[/red]")
+        raise typer.Exit(1)
+
+    upstream = manifest.get("upstream_repo")
+    if not upstream:
+        console.print(f"[yellow]No upstream_repo defined. Cannot upgrade.[/yellow]")
+        raise typer.Exit(1)
+        
+    try:
+        # Fetch status to get latest
+        result = subprocess.run(
+            ["git", "ls-remote", "--tags", "--refs", "--sort=-v:refname", upstream],
+            capture_output=True, text=True, check=True
+        )
+        lines = result.stdout.splitlines()
+        if not lines:
+             console.print("[red]No tags found upstream.[/red]")
+             return
+             
+        # Latest is the first one due to sort=-v:refname
+        latest_tag = lines[0].split("/")[-1]
+        
+        console.print(f"[bold green]Upgrading {name} -> {latest_tag}[/bold green]")
+        install_extension(name, version=latest_tag)
+        
+    except subprocess.CalledProcessError as e:
+         console.print(f"[red]Upgrade failed: {e}[/red]")
+
 @app.command("uninstall")
 def uninstall_extension(name: str, force: bool = typer.Option(False, "--force", "-f")):
     """Clean up build artifacts (removes 'build' directory)."""
@@ -387,3 +468,8 @@ def uninstall_extension(name: str, force: bool = typer.Option(False, "--force",
     else:
         console.print(f"[yellow]No build directory found for {name}.[/yellow]")
 
+@app.command("remove")
+def remove_extension(name: str, force: bool = typer.Option(False, "--force", "-f")):
+    """Alias for uninstall."""
+    uninstall_extension(name, force)
+
diff --git a/server/cli/src/quanuxctl/main.py b/server/cli/src/quanuxctl/main.py
@@ -52,9 +52,31 @@
 app.add_typer(topstepx.app, name="topstepx", help="Manage TopstepX Extension.")
 app.add_typer(topstepx.app, name="ts", help="Alias for topstepx", hidden=True)
 
+app.add_typer(geminicli.app, name="geminicli", help="Manage Gemini CLI Integration.")
 app.add_typer(geminicli.app, name="geminicli", help="Manage Gemini CLI Integration.")
 app.add_typer(geminicli.app, name="gemini", help="Alias for geminicli", hidden=True)
 
+# Top-level aliases for common extension operations
+@app.command("install")
+def install(name: str, version: str = typer.Option(None, "--version", "-v")):
+    """Install a QuanuX extension (Alias for 'ext install')."""
+    extensions.install_extension(name, version)
+
+@app.command("remove")
+def remove(name: str, force: bool = typer.Option(False, "--force", "-f")):
+    """Remove a QuanuX extension (Alias for 'ext remove')."""
+    extensions.remove_extension(name, force)
+
+@app.command("upgrade")
+def upgrade(name: str):
+    """Auto-upgrade extension (Alias for 'ext upgrade')."""
+    extensions.upgrade(name)
+
+@app.command("upgradeable")
+def upgradeable(name: str):
+    """Check for updates (Alias for 'ext upgradeable')."""
+    extensions.upgradeable(name)
+
 
 @app.command()
 def mcp():

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+Subproject commit 6908dc8c1084eeb7af7f322d35216e9965684489`