@grifhinz/logics-manager 2.3.0 → 2.3.1

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/AlexAgo83/logics-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/AlexAgo83/logics-manager/actions/workflows/ci.yml)
 [![License](https://img.shields.io/github/license/AlexAgo83/logics-manager)](LICENSE)
-![Version](https://img.shields.io/badge/version-v2.3.0-4C8BF5)
+![Version](https://img.shields.io/badge/version-v2.3.1-4C8BF5)
 ![VS Code](https://img.shields.io/badge/VS%20Code-1.86.0-007ACC?logo=visualstudiocode&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/TypeScript-5.3.3-3178C6?logo=typescript&logoColor=white)
 ![Vitest](https://img.shields.io/badge/Vitest-2.1.8-6E9F18?logo=vitest&logoColor=white)
@@ -58,6 +58,15 @@ python3.11 -m pip install .
 logics-manager --help
 ```
 
+On Debian, Ubuntu, or WSL environments where Python is externally managed, use `pipx` instead of installing into the system Python:
+
+```bash
+sudo apt update
+sudo apt install pipx python3-venv
+pipx ensurepath
+pipx install logics-manager
+```
+
 Or install the npm package:
 
 ```bash
@@ -197,6 +206,32 @@ To update the installed CLI later:
 logics-manager self-update
 ```
 
+If `self-update` reports an externally managed Python environment, migrate the Python install through `pipx`:
+
+```bash
+sudo apt update
+sudo apt install pipx python3-venv
+pipx ensurepath
+pipx install --force logics-manager
+```
+
+For npm installs, update with:
+
+```bash
+npm install -g @grifhinz/logics-manager@latest
+```
+
+If npm reports a successful update but `logics-manager --version` still shows an older version, another installation is earlier on `PATH`. Diagnose it with:
+
+```bash
+command -v -a logics-manager
+npm prefix -g
+npm list -g @grifhinz/logics-manager --depth=0
+"$(npm prefix -g)/bin/logics-manager" --version
+```
+
+If the direct npm binary shows the expected version, remove the older Python install or move the npm global `bin` directory earlier on `PATH`.
+
 ## VS Code Extension
 
 The VS Code extension is the human cockpit around the same runtime. It helps you:

package/VERSION

@@ -1 +1 @@
-2.3.0
+2.3.1

package/logics_manager/cli.py

@@ -1,9 +1,11 @@
 from __future__ import annotations
 
 import argparse
+import json
 from importlib import metadata
 import subprocess
 import sys
+import sysconfig
 from shutil import which
 from pathlib import Path
 
@@ -133,6 +135,48 @@ def get_cli_version() -> str:
     return "0.0.0"
 
 
+def _is_running_inside_venv() -> bool:
+    return sys.prefix != getattr(sys, "base_prefix", sys.prefix)
+
+
+def _is_externally_managed_python() -> bool:
+    if _is_running_inside_venv():
+        return False
+    stdlib = sysconfig.get_path("stdlib")
+    return bool(stdlib and (Path(stdlib) / "EXTERNALLY-MANAGED").exists())
+
+
+def _is_running_from_npm_package() -> bool:
+    package_json = Path(__file__).resolve().parents[1] / "package.json"
+    try:
+        payload = json.loads(package_json.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return False
+    return payload.get("name") == DEFAULT_SELF_UPDATE_PACKAGE
+
+
+def _print_externally_managed_update_guidance(package_name: str) -> None:
+    print(
+        "\n".join(
+            [
+                "This Python installation is externally managed, so pip cannot safely update logics-manager in the system environment.",
+                "",
+                "Recommended fix:",
+                "  sudo apt update",
+                "  sudo apt install pipx python3-venv",
+                "  pipx ensurepath",
+                f"  pipx install --force {package_name}",
+                "",
+                "If you installed the npm package instead, run:",
+                f"  npm install -g {DEFAULT_SELF_UPDATE_PACKAGE}@latest",
+                "",
+                "Advanced override, at your own risk:",
+                f"  logics-manager self-update --manager pip --break-system-packages",
+            ]
+        )
+    )
+
+
 def _is_json_mode(argv: list[str]) -> bool:
     return "--json" in argv or any(argv[index] == "--format" and index + 1 < len(argv) and argv[index + 1] == "json" for index in range(len(argv)))
 
@@ -208,20 +252,29 @@ def main(argv: list[str] | None = None) -> int:
         parser.add_argument("--manager", choices=("auto", "pip", "npm"), default="auto")
         parser.add_argument("--package", default=DEFAULT_SELF_UPDATE_PACKAGE)
         parser.add_argument("--python-package", default=DEFAULT_SELF_UPDATE_PY_PACKAGE)
+        parser.add_argument("--break-system-packages", action="store_true")
         parser.add_argument("--dry-run", action="store_true")
         parsed = parser.parse_args(rest)
 
         manager = parsed.manager
         if manager == "auto":
-            try:
-                metadata.version(parsed.python_package)
-            except metadata.PackageNotFoundError:
-                manager = "npm" if which("npm") else "pip"
+            if _is_running_from_npm_package() and which("npm"):
+                manager = "npm"
             else:
-                manager = "pip"
+                try:
+                    metadata.version(parsed.python_package)
+                except metadata.PackageNotFoundError:
+                    manager = "npm" if which("npm") else "pip"
+                else:
+                    manager = "pip"
 
         if manager == "pip":
+            if _is_externally_managed_python() and not parsed.break_system_packages:
+                _print_externally_managed_update_guidance(parsed.python_package)
+                return 1
             command = [sys.executable, "-m", "pip", "install", "--upgrade", parsed.python_package]
+            if parsed.break_system_packages:
+                command.append("--break-system-packages")
         else:
             npm = which("npm")
             if not npm:

package/package.json

@@ -2,7 +2,7 @@
   "name": "@grifhinz/logics-manager",
   "displayName": "Logics Orchestrator",
   "description": "Visual orchestration for Logics workflows inside VS Code.",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "publisher": "cdx-logics",
   "icon": "clients/shared-web/media/icon.png",
   "repository": {

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "logics-manager"
-version = "2.3.0"
+version = "2.3.1"
 description = "Canonical Logics CLI"
 requires-python = ">=3.10"